# 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 `![Status](…)` 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_` (path `/`, valid for 30 days, `SameSite=Lax`, `Secure`). Send it with later requests to both endpoints. A new password set with [Update Status Page](/api/status-pages/update-status-page) invalidates every cookie issued before. The check allows 10 attempts per minute per IP address and page; beyond that it answers `429` with `data.retryAfter`. Errors: `400 passwordRequired` (empty or missing password), `401 invalidPassword` (wrong password), `404 statusPageNotFound` (no published page with this slug, or the page is not password protected). A page with an IP allowlist (`ipAllowlist`) answers `403 statusPageIpNotAllowed` to visitors from other networks, whatever its visibility. This applies to both lookups and to the password check of a protected page (verify-password), which then does not check the password at all. The address that counts is the one our reverse proxy sees, not an `X-Forwarded-For` header sent by the client. With audience groups (`audienceGroups`), `components` leaves out the components of groups the visitor does not belong to (signed in with a verified email address of one of the group's domains; admins and editors of the page see everything), together with incidents and maintenance that only affect them; `overallStatus` and `overallState` are computed from what the visitor sees. Responses for a page with an IP allowlist or audience groups carry `Cache-Control: private, no-store`. Badge (`/status/:slug/badge.svg`), embed widget (`/status/:slug/embed`), Atom/RSS feeds and subscriptions exist only for pages with `visibility: public` and neither IP allowlist nor audience groups; for every other page they answer `404` like a missing page. **Preview of an unpublished page.** `GET /api/status-pages/public/:slug` also answers for a page with `isPublished: false` when the request is signed in as a member of the page's own organization with access to the design editor (`admin`, `editor` or `readonly`) and, for a page with a customer, that customer in scope. The response is the same, with `isPublished: false` and `Cache-Control: private, no-store`; the public page shows a "Preview, not public" banner. Everyone else, including members of other organizations and anonymous visitors, gets `404 statusPageNotFound`. The lookup by ID, the badge, the widget, the feeds and custom domains serve published pages only. ## Response ```json { "statusPage": { "id": 1, "name": "Production Status", "slug": "production-status", "description": "Real-time status of our production services", "visibility": "public", "isPublished": true, "showRecentIncidents": true, "showRecentMaintenance": true, "overallState": "degraded", "overallStatus": "partial_outage", "smsSubscriptionsEnabled": true, "pushPublicKey": "BOr3...base64url...", "productName": "Northwind Monitoring", "createdAt": "2026-01-15T10:00:00.000Z", "updatedAt": "2026-01-15T10:00:00.000Z" }, "websites": [ { "id": 101, "name": "Main Site", "url": null, "status": "active", "state": "operational", "publicStatus": "operational"… ### Get Status Page URL: https://docs.uptimeify.io/api/status-pages/get-status-page Description: Returns one status page by numeric id or publicId, in the same shape as an entry of List Status Pages. Summary: `GET /api/status-pages/{id}` ## Access Same access and visibility as [List Status Pages](/api/status-pages/list-status-pages): a page outside your scope answers `404`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/status-pages/1" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "id": 1, "publicId": "cccccccc-cccc-4ccc-8ccc-cccccccccccc", "organizationId": 10, "customerId": 5, "includeCustomerMonitors": true, "managementType": "managed", "canEdit": true, "customerPublicId": "dddddddd-dddd-4ddd-8ddd-dddddddddddd", "customerName": "Acme GmbH", "name": "Acme Status", "slug": "acme", "description": null, "visibility": "public", "hasPassword": false, "accessPasswordSetAt": null, "isPublished": true, "showRecentIncidents": true, "showRecentMaintenance": true, "subscriptionsEnabled": false, "subscriptionDelayMinutes": 5, "smsSubscriptionsEnabled": false, "pushSubscriptionsEnabled": false, "monitorUpdatesEnabled": true, "designConfig": null, "hiddenMonitors": [], "ipAllowlist": [], "audienceGroups": [], "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-01T08:00:00.000Z", "customDomain": { "id": 12, "hostname": "status.acme.example", "status": "active", "verifiedAt": "2026-06-02T08:00:00.000Z", "lastVerificationError": null, "lastVerificationErrorAt": null, "verificationToken": "uptimeify-verify-abc123" } } ``` `customerId`, `customerPublicId` and `customerName` are `null` for a page without a customer. Such a page is visible to organization-wide roles and API tokens only; a customer-scoped caller does not see it. `includeCustomerMonitors` says whether the customer's monitors appear automatically. The components of a page are read with [List Status Page Components](/api/status-pages/list-status-page-components) and [List Status Page Component Groups](/api/status-pages/list-status-page-component-groups). `canEdit` (since 30 October 2026) says whether you may change this page and what hangs off it (settings, components, custom domain, subscribers, incidents, maintenance). Organization-wide callers: `true` with the role `admin` or `editor`. Customer-bound users and tokens (also with the role `readonly`): `true` for `self_service` pages, for `managed` pages only when the customer has `canEditManaged`. It is the same rule the write endpoints apply, see [Who may change a status page](/api/status-pages#who-may-change-a-status-page). `ipAllowlist` and `audienceGroups` (since 28 October 2026) carry the page's IP allowlist (as `addr/prefix`) and its audience groups (`name`, `emailDomains`, `componentIds` as numeric ids); both are `[]` when not set. **Compatibility:** since 27 October 2026 `customerId` can be `null` in responses (a page of the whole organization, without a customer), together with `customerPublicId` and `customerName` where present. A client that assumes `customerId` is always a number must handle `null`. ## Common errors - `400 Bad Request` when the id is neither a number nor a UUID, or your account has no organization - `401 Unauthorized` when you are not logged in - `403 Forbidden` when your role may not read status pages - `404 Not Found` (`statusPageNotFound`) when the page does not exist or is outside your scope ### Get Status Page Design URL: https://docs.uptimeify.io/api/status-pages/get-status-page-design Description: Returns the current visual design configuration for a status page. Requires the role `admin`, `editor` or `readonly`. Summary: `GET /api/status-pages/:id/design` ## 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/design" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "designConfig": { "layout": "timeline", "colorScheme": "dark", "accentColor": "#f59e0b", "headerStyle": "simple", "fontFamily": "system", "cardRadius": "md", "pageWidth": "lg", "customTitle": "", "customSubtitle": "", "showPoweredBy": true, "showUptimeStats": true, "showServiceUrls": false, "showLastChecked": false, "showHistory": true, "historyDays": 30, "showIncidents": true, "incidentLimit": 5, "incidentDays": 30, "showMaintenance": true, "maintenanceLimit": 5, "maintenanceDays": 30, "customCss": "", "statusLabels": { "majorOutage": "Disruption" } } } ``` If no design has been saved yet all fields reflect the defaults. ## Common errors - `401 Unauthorized`: not authenticated - `403 Forbidden` (`forbidden`): role is not `admin`, `editor` or `readonly`, or a global supporter - `404 Not found`: status page does not exist ### Get Status Page Domain URL: https://docs.uptimeify.io/api/status-pages/get-status-page-domain Description: Returns one status-page custom domain of your organization, in the same { domain, dns } shape as Add Status Page Domain. Summary: `GET /api/status-pages/domains/{id}` ## Access Same read access as [List Status Pages](/api/status-pages/list-status-pages). Only domains of your organization with the role `status_page` are returned. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/status-pages/domains/12" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "domain": { "id": 12, "hostname": "status.acme.example", "status": "pending", "role": "status_page", "verificationToken": "uptimeify-verify-abc123", "verifiedAt": null, "lastVerificationError": null, "lastVerificationErrorAt": null, "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-01T08:00:00.000Z", "statusPageId": 7 }, "dns": { "txtName": "_verify-status.status.acme.example", "txtValue": "uptimeify-verify-abc123" } } ``` `domain.statusPageId` is the id of the status page the domain is bound to, `null` while it is not bound to a page yet. `domain.lastVerificationError` is the diagnosis of the last failed [verification](/api/status-pages/verify-status-page-domain) (same fields as the `domainVerificationFailed` error data), with `domain.lastVerificationErrorAt`; both are `null` once a verification succeeded. For a live check of DNS and certificate use [Status Page Domain Diagnostics](/api/status-pages/get-status-page-domain-diagnostics). ## Common errors - `400 Bad Request` (`invalidDomainId`) when the id is not a positive number - `401 Unauthorized` when you are not logged in - `403 Forbidden` when your role may not read status pages - `404 Not Found` (`domainNotFound`) when the domain does not exist or belongs to another organization ### Status Page Domain Diagnostics URL: https://docs.uptimeify.io/api/status-pages/get-status-page-domain-diagnostics Description: Live DNS and certificate check of one status-page custom domain: authoritative nameservers, TXT record seen, propagation, certificate state, last failed verification. Summary: `GET /api/status-pages/domains/{id}/diagnostics` Runs the checks live on every call and writes nothing. Use it when a domain does not verify or does not serve HTTPS. ## Access Same read access as [Get Status Page Domain](/api/status-pages/get-status-page-domain). ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/status-pages/domains/12/diagnostics" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "domainId": 12, "hostname": "status.acme.example", "status": "active", "checkedAt": "2026-10-29T09:30:00.000Z", "verification": { "recordFound": true, "recordName": "_verify-status.status.acme.example", "expected": "uptimeify-verify-abc123", "lookup": "records", "observed": ["uptimeify-verify-abc123"], "nameservers": { "zone": "acme.example", "hosts": ["ns1.dns-provider.example", "ns2.dns-provider.example"] }, "authoritative": { "nameserver": "ns1.dns-provider.example", "lookup": "records", "observed": ["uptimeify-verify-abc123"] }, "propagation": "propagated" }, "certificate": { "state": "valid", "errorCode": null, "errorMessage": null, "issuer": "Let's Encrypt", "validFrom": "2026-10-01T00:00:00.000Z", "validTo": "2026-12-30T00:00:00.000Z", "daysUntilExpiry": 62 }, "lastVerificationError": null, "lastVerificationErrorAt": null } ``` | Field | Description | |-------|-------------| | `verification` | The live TXT check, `null` when the domain has no verification token. Same fields as the `domainVerificationFailed` error data of the verify endpoint, plus `recordFound` (`true`: the token is published, verify would succeed). | | `verification.nameservers` | The zone the hostname is delegated in and its authoritative nameservers; `null` if that could not be determined. | | `verification.authoritative` | What one of those nameservers answered when asked directly, bypassing every cache; `null` if none could be asked. Only public nameserver addresses are queried. | | `verification.propagation` | `propagated` (our resolver sees the token), `propagating` (your nameserver has it, our resolver not yet; retry after the TTL), `not_published` (not even your nameserver has it), `unknown` (no nameserver could be asked). | | `certificate.state` | What a browser gets on `https://`: `valid`, `invalid` (a certificate is served but fails verification, reason in `errorCode`), `handshake_failed` (no TLS handshake: the certificate may still be issuing, or the CNAME does not point to us yet), `unreachable` (`errorCode` `not_resolved` or `private_address`), `not_active` (the domain is not activated yet, no certificate is issued before that, nothing was probed). | | `certificate.errorCode` | `expired`, `not_yet_valid`, `hostname_mismatch`, `untrusted`, `not_resolved`, `private_address` or `null`. | | `lastVerificationError`, `lastVerificationErrorAt` | The last failed verification as stored on the domain, `null` after a successful one. | ## Common errors - `400 Bad Request` (`invalidDomainId`) when the id is not a positive number - `401 Unauthorized` when you are not logged in - `403 Forbidden` when your role may not read status pages - `404 Not Found` (`domainNotFound`) when the domain does not exist or belongs to another organization ### Get Status Page Maintenance URL: https://docs.uptimeify.io/api/status-pages/get-status-page-maintenance Description: Returns one scheduled maintenance with its pages, components and updates. Summary: `GET /api/status-pages/maintenances/{id}` `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. ## Access Organization `admin`, `editor` and `readonly`. A customer-scoped user or API token only sees maintenance whose status pages all belong to a customer in its scope. Maintenance of another organization answers `404` (`statusPageMaintenanceNotFound`). Path ids take the numeric id or the `publicId`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/status-pages/maintenances/12" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `200 OK`: ```json { "id": 12, "publicId": "3f1c2a9e-5b7d-4c8e-9a1f-2b3c4d5e6f70", "organizationId": 4, "title": "Database upgrade", "description": "Checkout may be slow for a few minutes.", "scheduledFor": "2026-11-03T22:00:00.000Z", "scheduledUntil": "2026-11-03T23:00:00.000Z", "state": "scheduled", "notifyOnSchedule": true, "reminderMinutesBefore": 60, "notifyOnStart": false, "notifyOnComplete": true, "cancelledAt": null, "statusPageIds": [1], "componentIds": [7], "links": [ { "statusPageId": 1, "statusPagePublicId": "0b6f3c1e-8d2a-4f5b-9c7e-1a2b3c4d5e6f", "statusPageName": "Acme Status", "componentId": 7, "componentPublicId": "5a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "componentName": "Checkout" } ], "updates": [], "createdAt": "2026-10-28T09:00:00.000Z", "updatedAt": "2026-10-28T09:00:00.000Z" } ``` ## 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` (`statusPagesModuleDisabled`) when the status pages module is not activated - `404 Not Found` (`statusPageMaintenanceNotFound`) when the maintenance does not exist or belongs to another organization ### Get Status Page Module URL: https://docs.uptimeify.io/api/status-pages/get-status-page-module Description: Returns whether the status pages module is enabled for your organization. Summary: `GET /api/status-pages/module` Status pages are a module that each organization activates once. While it is off, every status page endpoint except this one, [Activate Status Page Module](/api/status-pages/activate-status-page-module) and the public endpoints answers `403` with `data.code: statusPagesModuleDisabled`. Organizations that already had a status page when the module was introduced were activated automatically. ## Access Roles `admin`, `editor` and `readonly` of the organization. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/status-pages/module" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "enabled": true, "activatedAt": "2026-10-27T09:00:00.000Z", "smsQuotaAvailable": true } ``` `activatedAt` is `null` while the module was never activated. `smsQuotaAvailable` is `true` while your organization can send an SMS (included SMS left, or overage enabled and under the SMS safety cap). While it is `false`, switching `smsSubscriptionsEnabled` on answers `403 smsQuotaRequired` and public pages offer no SMS subscription; pages that already have it on keep the setting and their SMS subscribers. ## Common errors - `400 Bad Request` (`userMustBelongToOrg`) when your account has no organization - `401 Unauthorized` when you are not logged in - `403 Forbidden` when your role may not read status pages ### Get Status Page Template URL: https://docs.uptimeify.io/api/status-pages/get-status-page-template Description: Returns one template. Summary: `GET /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`, `editor` and `readonly`, also customer-scoped. Templates belong to the whole organization. A template of another organization answers `404` (`statusPageTemplateNotFound`). Path ids take the numeric id or the `publicId`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/status-pages/templates/4" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `200 OK`, the same shape as an entry of [List Status Page Templates](/api/status-pages/list-status-page-templates): ```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` (`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 ### List Subscribers of All Status Pages URL: https://docs.uptimeify.io/api/status-pages/list-all-subscribers Description: Returns the subscribers of every status page you may manage in one paged list, with filters. Organization-wide: admin or editor; customer-bound: the pages you may maintain. Summary: `GET /api/status-pages/subscribers` **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. The same rows as [List Status Page Subscribers](/api/status-pages/list-subscribers), across pages: exactly the status pages whose subscriber list you could open one by one (your organization, your customer scope; pages without a customer only with an organization-wide scope). Subscribers cannot be created through the API: a subscription only exists once the recipient has confirmed it (double opt-in). To remove one, use [Delete Status Page Subscriber](/api/status-pages/delete-subscriber) with the row's `statusPagePublicId`. ## Query Parameters | Parameter | Description | |-----------|-------------| | `page` | Page number, default `1` | | `perPage` | Rows per page, default `50`, capped at `200` | | `statusPageId` | Only this status page (ID or `publicId`). An unknown page or one outside your scope yields an empty list | | `statusPageIds` | Only these status pages: comma-separated IDs or `publicId`s, at most 50, combined with `statusPageId`. Pages outside your scope contribute no rows | | `channel` | `email`, `sms`, `push`, `webhook`, `slack` or `teams` | | `status` | `pending`, `confirmed`, `unsubscribed` or `disabled` | | `search` | Case-insensitive match on the email address or the status page name (at most 200 characters) | ## Example (cURL) ```bash curl "$BASE_URL/api/status-pages/subscribers?status=confirmed&perPage=100" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "items": [ { "id": 43, "statusPageId": 7, "statusPagePublicId": "db58058e-4b58-4d97-a314-3bb8e279a182", "statusPageName": "Acme Status", "email": null, "channel": "slack", "target": "https://hooks.slack.com/…", "componentIds": [12], "componentNames": ["Checkout"], "status": "confirmed", "locale": "de", "createdAt": "2026-10-27T09:00:00.000Z", "confirmedAt": "2026-10-27T09:01:00.000Z" } ], "total": 1, "page": 1, "perPage": 100 } ``` Newest first. Field meanings as in [List Status Page Subscribers](/api/status-pages/list-subscribers): `email` is `null` for the URL channels, `target` carries only the origin of the target URL, never the full URL. `componentNames` lists the names of `componentIds` in the same order; both are `null` when the subscriber follows the whole page. ## Common errors - `401 Unauthorized` when you are not authenticated - `403 Forbidden` (`data.code: forbidden`) when you are an organization-wide caller without the role admin or editor - `403 Forbidden` (`data.code: statusPagesModuleDisabled`) when the status page module is not active for your organization - `400 Bad Request` (`data.code: invalidRequestBody`) when `page`, `perPage`, `channel`, `status` or `search` is invalid, or `statusPageIds` names more than 50 pages - `400 Invalid Status page identifier` (`data.code: invalidIdentifier`) when `statusPageId` or an entry of `statusPageIds` is neither a numeric ID nor a UUID ### List Status Page Component Groups URL: https://docs.uptimeify.io/api/status-pages/list-status-page-component-groups Description: Returns every component group of a status page, ordered by sort. Summary: `GET /api/status-pages/{id}/groups` Groups bundle [components](/api/status-pages/list-status-page-components) under a heading on the public page. The list holds every group of the page in one page of results, ordered by `sort`, then `id`. A page has at most 500 groups. ## Access Organization `admin`, `editor` and `readonly`. 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`). `:id` takes the numeric id or the `publicId` of the status page. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/status-pages/1/groups" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "items": [ { "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" } ], "total": 1, "page": 1, "perPage": 1 } ``` `collapsed` controls whether the group starts collapsed on the public page. ## 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 ### List Status Page Components URL: https://docs.uptimeify.io/api/status-pages/list-status-page-components Description: Returns every component of a status page, ordered by sort. Summary: `GET /api/status-pages/{id}/components` A component is one row on the status page: a monitor (`sourceKind: monitor`), a third-party provider from our dependency monitoring (`sourceKind: dependency`) or an entry you maintain by hand (`sourceKind: manual`). Components can sit in a [group](/api/status-pages/list-status-page-component-groups). The list holds every component of the page in one page of results, ordered by `sort`, then `id`. A page has at most 500 components. The monitors the page includes automatically through `includeCustomerMonitors` are not components and do not appear here. ## Access Organization `admin`, `editor` and `readonly`. 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`). `:id` takes the numeric id or the `publicId` of the status page. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/status-pages/1/components" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "items": [ { "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", "updatedAt": "2026-10-27T09:00:00.000Z" }, { "id": 8, "publicId": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a", "statusPageId": 1, "groupId": null, "sort": 1, "name": "Payment provider", "description": "Card payments at checkout", "showUptime": true, "sourceKind": "manual", "monitorType": null, "monitorId": null, "manualStatus": "operational", "dependencySlug": null, "createdAt": "2026-10-27T09:05:00.000Z", "updatedAt": "2026-10-27T09:05:00.000Z" } ], "total": 2, "page": 1, "perPage": 2 } ``` | Field | Description | |---|---| | `groupId` | Numeric id of the group, or `null` when the component is not in a group. | | `sourceKind` | `monitor`, `dependency` or `manual`. | | `monitorType`, `monitorId` | The monitor of a monitor component; `null` for a manual one. `monitorType` is one of `http`, `dns`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp`, `imap_pop`. | | `manualStatus` | State of a manual component: `operational`, `degraded`, `partial_outage`, `major_outage` or `maintenance`; `null` for the other kinds. | | `dependencySlug` | Provider slug of a dependency component (`GET /api/public/dependencies`); `null` for the other kinds. | | `showUptime` | Whether the component shows its availability bar on the page. | ## 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 ### List Status Page Maintenance URL: https://docs.uptimeify.io/api/status-pages/list-status-page-maintenance Description: Lists the scheduled maintenance of your status pages. Summary: `GET /api/status-pages/maintenances` ## Access Organization `admin`, `editor` and `readonly`. A customer-scoped user or API token only sees maintenance whose status pages all belong to a customer in its scope. Maintenance of another organization answers `404` (`statusPageMaintenanceNotFound`). Path ids take the numeric id or the `publicId`. ## Query Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `statusPageId` | number\|string | - | Only maintenance shown on this status page (id or `publicId`). | | `state` | string | - | Comma-separated: `scheduled`, `in_progress`, `completed`, `cancelled`. | | `page` | number | `1` | | | `perPage` | number | `50` | Capped at 200. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/status-pages/maintenances?state=scheduled,in_progress" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `200 OK`, newest start first. Each item has the same shape as [Get Status Page Maintenance](/api/status-pages/get-status-page-maintenance): ```json { "items": [ { "id": 12, "title": "Database upgrade", "state": "scheduled", "...": "..." } ], "total": 1, "page": 1, "perPage": 50 } ``` ## 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` (`statusPagesModuleDisabled`) when the status pages module is not activated - `404 Not Found` (`statusPageNotFound`) when a status page does not exist or belongs to another organization - `400 Bad Request` (`invalidRequestBody`) when `state`, `page` or `perPage` is not valid ### List Status Page Templates URL: https://docs.uptimeify.io/api/status-pages/list-status-page-templates Description: Lists the incident and update templates of your organization. Summary: `GET /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`, `editor` and `readonly`, also customer-scoped. Templates belong to the whole organization. A template of another organization answers `404` (`statusPageTemplateNotFound`). Path ids take the numeric id or the `publicId`. ## Query Parameters - `kind` (optional): `incident` or `update`. Any other value answers `400` (`invalidRequestBody`). ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/status-pages/templates?kind=incident" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `200 OK`, every template (at most 200), by name: ```json { "items": [{ "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" }], "total": 1, "page": 1, "perPage": 1 } ``` ## Common errors - `400 Bad Request` (`invalidRequestBody`) when `kind` is not `incident` or `update` - `401 Unauthorized` when you are not logged in - `403 Forbidden` (`statusPagesModuleDisabled`) when the status pages module is not activated ### List Status Pages URL: https://docs.uptimeify.io/api/status-pages/list-status-pages Description: Returns all status pages for the organization. Each page includes its custom domain info if configured. Summary: `GET /api/status-pages` ## 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/status-pages?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": 1, "publicId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "organizationId": 1, "customerId": 5, "includeCustomerMonitors": true, "managementType": "managed", "canEdit": true, "customerPublicId": "f7e6d5c4-b3a2-1098-7654-321fedcba098", "name": "Production Status", "slug": "production-status", "description": "Real-time status of our production services", "visibility": "public", "isPublished": true, "showRecentIncidents": true, "showRecentMaintenance": true, "customDomainId": null, "ipAllowlist": [], "audienceGroups": [], "createdAt": "2026-01-15T10:00:00.000Z", "updatedAt": "2026-01-15T10: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 (`{ "statusPages": [...] }`), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. `customerId`, `customerPublicId` and `customerName` are `null` for a page without a customer. Such a page is visible to organization-wide roles and API tokens only; a customer-scoped caller does not see it. `includeCustomerMonitors` says whether the customer's monitors appear automatically. The components of a page are read with [List Status Page Components](/api/status-pages/list-status-page-components) and [List Status Page Component Groups](/api/status-pages/list-status-page-component-groups). `canEdit` (since 30 October 2026) says whether you may change this page and what hangs off it (settings, components, custom domain, subscribers, incidents, maintenance). Organization-wide callers: `true` with the role `admin` or `editor`. Customer-bound users and tokens (also with the role `readonly`): `true` for `self_service` pages, for `managed` pages only when the customer has `canEditManaged`. It is the same rule the write endpoints apply, see [Who may change a status page](/api/status-pages#who-may-change-a-status-page). `ipAllowlist` and `audienceGroups` (since 28 October 2026) carry the page's IP allowlist (as `addr/prefix`) and its audience groups (`name`, `emailDomains`, `componentIds` as numeric ids); both are `[]` when not set. **Compatibility:** since 27 October 2026 `customerId` can be `null` in responses (a page of the whole organization, without a customer), together with `customerPublicId` and `customerName` where present. A client that assumes `customerId` is always a number must handle `null`. ## Common errors - `401 Unauthorized` when not authenticated ### List Status Page Subscribers URL: https://docs.uptimeify.io/api/status-pages/list-subscribers Description: Returns the email and RSS subscribers of a status page, plus exact counts by status. Organization-wide: admin or editor; customer-bound: by the page's ownership class. Summary: `GET /api/status-pages/:id/subscribers` **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. ## 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" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "total": 12, "confirmed": 9, "pending": 2, "unsubscribed": 1, "disabled": 0, "subscribers": [ { "id": 42, "email": "reader@example.com", "channel": "email", "target": null, "componentIds": null, "status": "confirmed", "locale": "en", "createdAt": "2026-08-01T12:00:00.000Z", "confirmedAt": "2026-08-01T12:05:00.000Z" }, { "id": 43, "email": null, "channel": "slack", "target": "https://hooks.slack.com/…", "componentIds": [12], "status": "confirmed", "locale": "de", "createdAt": "2026-10-27T09:00:00.000Z", "confirmedAt": "2026-10-27T09:01:00.000Z" } ] } ``` `status` is one of `pending`, `confirmed`, `unsubscribed`, or `disabled` (a webhook, Slack, Teams, SMS or push subscription switched off after 5 failed deliveries in a row). `channel` is `email`, `sms`, `push`, `webhook`, `slack` or `teams`; `email` is `null` for all but `email`, and `target` then carries the origin of the target URL or push endpoint only, never the full URL (the URL of an incoming webhook is the credential), or for `sms` the number as country code and last two digits (`+49…67`). `componentIds` lists the components of this page the subscriber follows, `null` for the whole page. `confirmedAt` is `null` until the subscriber confirms. `total`, `confirmed`, `pending`, `unsubscribed`, and `disabled` are exact counts computed independently of the `subscribers` array; `subscribers` itself is capped at 5000 rows, newest first, use [Export Status Page Subscribers](/api/status-pages/export-subscribers) to retrieve every row on a larger page. ## 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 The last two rows share the same message but differ in `data.code`: a malformed or entirely unknown `id` never carries a `data.code`; only an `id` that resolves to a row you may not see does. ### Post Status Page Maintenance Update URL: https://docs.uptimeify.io/api/status-pages/post-status-page-maintenance-update Description: Publishes an update to a maintenance on the page and to subscribers. Summary: `POST /api/status-pages/maintenances/{id}/updates` Adds a public update to a maintenance, before, during or after it. ## 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 | |-------|------|----------|---------|-------------| | `body` | string | Yes | - | The update text (1-5000 chars), shown on the public page. | | `notifySubscribers` | boolean | No | `true` | Send it to subscribers as `maintenance_update`. The same text twice on the same maintenance is sent once. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/status-pages/maintenances/12/updates" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"body": "The upgrade takes 20 minutes longer than planned."}' ``` ## Response `201 Created`: ```json { "id": 31, "publicId": "7c2d4e6f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "body": "The upgrade takes 20 minutes longer than planned.", "createdAt": "2026-11-03T22:40:00.000Z" } ``` ## Common errors - `400 Bad Request` (`invalidRequestBody`) when a field is missing, has the wrong type or is unknown; `data.issues` names the field - `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 was cancelled ### Remove Custom Domain from Status Page URL: https://docs.uptimeify.io/api/status-pages/remove-status-page-domain Description: Removes a custom domain from a status page. Deletes the domain record; the status page's customDomainId is automatically set to null. Organization-wide: admin or editor; customer-bound: by the page's ownership class. Summary: `DELETE /api/status-pages/domains/:id` **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`. ## Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | `id` | number | The domain ID to remove | ## Example (cURL) ```bash curl -X DELETE "$BASE_URL/api/status-pages/domains/42" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `204 No Content` ## 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 domain does not exist - `422 Unprocessable Entity` when the domain ID is invalid ### Reorder Status Page Components URL: https://docs.uptimeify.io/api/status-pages/reorder-status-page-components Description: Sets position and group of many components in one call. Summary: `PUT /api/status-pages/{id}/components/order` Sets `sort` and `groupId` of several components in one transaction, for example after drag and drop. Every listed component and group must belong to this page; otherwise the call answers `404` and nothing is written. Components you do not list stay as they are. ## 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 | Description | |-------|------|----------|-------------| | `items` | array | Yes | 1 to 500 entries. | | `items[].id` | number\|string | Yes | Id or `publicId` of the component. | | `items[].groupId` | number\|string\|null | Yes | Id or `publicId` of the target group, `null` for no group. | | `items[].sort` | number | Yes | New position, 0-100000. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PUT "$BASE_URL/api/status-pages/1/components/order" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "id": 8, "groupId": 3, "sort": 0 }, { "id": 7, "groupId": 3, "sort": 1 } ] }' ``` ## Response `200 OK` with every component of the page after the change, ordered by `sort`, in the same form as [List Status Page Components](/api/status-pages/list-status-page-components) (`{ items, total, page, perPage }`). ## Common errors - `400 Bad Request` (`invalidRequestBody`) when `items` is empty, has more than 500 entries or an entry 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 - `404 Not Found` (`statusPageComponentNotFound`) when a listed component does not exist on this page - `404 Not Found` (`statusPageComponentGroupNotFound`) when a listed `groupId` is not a group of this page ### Subscribe to a Status Page URL: https://docs.uptimeify.io/api/status-pages/subscribe-to-status-page Description: Public endpoint behind the subscribe form: email, SMS, browser push, webhook, Slack or Microsoft Teams, for the whole page or selected components. Double opt-in for every channel. Summary: `POST /api/status-pages/public/:slug/subscribe` No authentication. This is the endpoint the subscribe form on a public status page posts to. Every subscription starts as `pending` and becomes active only after the confirmation link was opened and confirmed: by mail for `email`, as a first message posted to the target for `webhook`, `slack` and `teams`, with a six-digit code by SMS for `sms` (entered on the status page), and by a first push that the page's service worker confirms by itself for `push`. Every message carries an unsubscribe link. The page must be published, public (no IP allowlist, no audience groups), have subscriptions switched on, and its organization must have the status page module enabled and not be suspended. Otherwise the endpoint answers the same `{ "ok": true }` and stores nothing. Existing subscribers of a page that is protected later (a visibility other than `public`, an IP allowlist or audience groups) receive no more notifications. `sms` and `push` are additionally opt-in per page (`smsSubscriptionsEnabled`, `pushSubscriptionsEnabled` on the status page, both off by default); `GET /api/status-pages/public/:slug` tells the form whether to offer them. `sms` is offered and accepted only while the organization has SMS quota as well. ## Request body | Field | Type | Required | Description | |-------|------|----------|-------------| | `channel` | string | no | `email` (default), `sms`, `push`, `webhook`, `slack` or `teams` | | `email` | string | for `email` | Recipient address | | `targetUrl` | string | for URL channels | `https` URL without credentials, publicly reachable. Slack: an incoming webhook URL. Teams: an incoming webhook or Workflows URL that accepts Adaptive Cards | | `phone` | string | for `sms` | Mobile number in international format, e.g. `+49 170 1234567` or `0049...`; spaces, dashes and brackets are ignored | | `pushSubscription` | object | for `push` | The browser's `PushSubscription.toJSON()`: `endpoint` (`https`, publicly reachable) and `keys.p256dh`, `keys.auth`, created with the page's `pushPublicKey` | | `componentIds` | array | no | Components of this page (numeric ID or `publicId`), at most 500. Omitted or empty: the whole page | | `locale` | string | no | `de...` for German, `da...` for Danish messages, anything else English | A URL, SMS or push subscription is stored encrypted. Its target is never returned in full: the subscriber list shows the origin of a URL or push endpoint, and of a phone number the country code and the last two digits. ## Example (cURL) ```bash curl -X POST "https://uptimeify.io/api/status-pages/public/acme/subscribe" \ -H "Content-Type: application/json" \ -d '{"channel":"webhook","targetUrl":"https://example.com/hooks/status","componentIds":[12]}' ``` ## Response `200 OK` ```json { "ok": true } ``` For `email` and `sms` the answer is always this (except `403 statusPageSmsUnavailable` below), also for an unknown page, an address or number that is already confirmed, or a rate-limited one, so the endpoint does not reveal whether an address, number or page exists. ## SMS The code SMS and every later SMS go out from the organization's SMS quota: within the included SMS, beyond that only with overage enabled for the organization, and never past its SMS safety cap. When no SMS budget is left, nothing is sent and the subscriber is not counted as failed. The code is valid for 15 minutes; the status page form confirms it with `POST /api/status-pages/public/:publicId/confirm` and `{ "phone": "...", "code": "123456" }` (5 attempts per number and hour). One number gets at most 3 codes per hour. An event SMS is a single SMS: page name, event and a short unsubscribe link; long titles are shortened. ## Browser push W3C Web Push with VAPID. Messages are end-to-end encrypted for the browser (RFC 8291) and travel through the push service of the browser vendor (Google, Mozilla, Apple, Microsoft), which cannot read them. The first push carries the confirmation, which the page'… ### Update Status Page URL: https://docs.uptimeify.io/api/status-pages/update-status-page Description: Updates a status page. At least one field must be provided. Requires the role `admin` or `editor`; customer-bound users and tokens (also `readonly`) update self-service pages of their customers. Summary: `PATCH /api/status-pages/:id` ## Request Body (all optional) | Field | Type | Description | |-------|------|-------------| | `customerId` | number\|null | Move the page to another customer of your organization. `null` detaches it from its customer (page of the whole organization); only organization-wide roles and API tokens may do that. | | `includeCustomerMonitors` | boolean | Show every monitor of the customer, except those in `hiddenMonitors`, automatically after the explicit components. A change of `customerId` leaves it as it is. | | `managementType` | string | `managed` or `self_service`. Only organization admins without a customer binding may change it (`403 managementTypeOrgOnly` otherwise). | | `name` | string | Display name (1-120 chars) | | `slug` | string | URL slug (1-120 chars, 409 on conflict) | | `description` | string\|null | Description (max 1000 chars). `null` clears it. | | `visibility` | string | `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 | Sets a new page password (8-200 characters). Required when the page becomes `password_protected` and has no password yet; otherwise omit it to keep the current one. A new password logs out every visitor who unlocked the page. The password cannot be removed: switching to another visibility keeps it stored (`hasPassword` stays `true`) and switching back reuses it. Never returned; the response shows `hasPassword` and `accessPasswordSetAt`. | | `ipAllowlist` | array | Replaces the IP allowlist: IPv4/IPv6 addresses or CIDR ranges, at most 50, stored as `addr/prefix`. `[]` removes the restriction. | | `audienceGroups` | array | Replaces all audience groups, at most 20: `[{ "name", "emailDomains", "componentIds" }]`. `[]` removes them. See below. | | `isPublished` | boolean | Publish or unpublish the page | | `showRecentIncidents` | boolean | Show recent incidents section | | `showRecentMaintenance` | boolean | Show recent maintenance section | | `smsSubscriptionsEnabled` | boolean | Offer SMS subscriptions on the public page (default `false`). Switching it off stops SMS to existing SMS subscribers too. Switching it on needs SMS quota (`403 smsQuotaRequired` otherwise); a page that already has it on keeps it. | | `pushSubscriptionsEnabled` | boolean | Offer browser push subscriptions on the public page (default `false`). Switching it off stops push to existing push subscribers too. | | `monitorUpdatesEnabled` | boolean | Monitors write to this page (default `true`): their state sets components and the page status, monitoring incidents show in the history and reach subscribers. `false`: the page only shows what you report or explicitly link (linked incidents, maintenance, Incident Management rules). | | `designConfig` | object | Visual design settings (layout, colors, typography, …). See [Update Status Page Design](/api/status-pages/update-status-page-design) for all fields. | | `hiddenMonitors` | array | 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. | When present, `hiddenMonitors` replaces the stored list in full; omit the field to leave it unchanged; send `[]` to show all monitors again. **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`. Switching to `password_protected` needs `accessPassword` only while the page has no stored password yet (`hasPassword: false`); otherwise the request is rejected with… ### Update Status Page Component URL: https://docs.uptimeify.io/api/status-pages/update-status-page-component Description: Changes name, description, group, position, uptime bar, manual state or monitor of a component. Summary: `PATCH /api/status-pages/{id}/components/{componentId}` ## 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 (all optional, at least one field) | Field | Type | Description | |-------|------|-------------| | `name` | string | Display name (1-120 chars). | | `description` | string\|null | Max 1000 chars. `null` clears it. | | `groupId` | number\|string\|null | Id or `publicId` of a group of this page. `null` moves the component out of its group. | | `sort` | number | Position, 0-100000. | | `showUptime` | boolean | Show the availability bar. | | `manualStatus` | string | Manual components only (or together with `sourceKind: "manual"`): `operational`, `degraded`, `partial_outage`, `major_outage` or `maintenance`. | | `sourceKind` | string | `monitor` or `manual`. Switches the component between following a monitor and a state you set yourself. `manual` drops the monitor link; `manualStatus` defaults to `operational`. `monitor` needs `monitorType` and `monitorId`. Not for `dependency` components. | | `monitorType` | string | Together with `monitorId`: the monitor the component follows (`http`, `dns`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp`, `imap_pop`). Links another monitor to a monitor component, or with `sourceKind: "monitor"` turns a manual one into a monitor component. Same rules as on create: a monitor of this organization, of the page's customer if it has one, and within the caller's customer scope. | | `monitorId` | number | Together with `monitorType`. | The component keeps its id, group, subscriptions and incident links when its source changes. A `dependency` component keeps its provider; delete it and create a new one instead. To move many components at once, use [Reorder Status Page Components](/api/status-pages/reorder-status-page-components). ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/status-pages/1/components/8" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "manualStatus": "partial_outage" }' ``` Follow a monitor instead of a manual state: ```bash curl -X PATCH "$BASE_URL/api/status-pages/1/components/8" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "sourceKind": "monitor", "monitorType": "http", "monitorId": 42 }' ``` ## Response `200 OK` with the updated component, in the same shape as on [List Status Page Components](/api/status-pages/list-status-page-components). ## Common errors - `400 Bad Request` (`invalidRequestBody`) when the body is empty or a field is invalid - `400 Bad Request` (`statusPageComponentNotManual`) when `manualStatus` is sent for a component that is not (or does not become) manual - `400 Bad Request` (`statusPageComponentSourceInvalid`) when `sourceKind: "monitor"` comes without a monitor for a manual component, a monitor is sent together with `sourceKind: "manual"`, or the component is a `dependency` component - `400 Bad Request` (`statusPageComponentMonitorCustomerMismatch`) when the monitor belongs to another customer than the page - `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 activate… ### Update Status Page Component Group URL: https://docs.uptimeify.io/api/status-pages/update-status-page-component-group Description: Renames, moves or collapses a component group. Summary: `PATCH /api/status-pages/{id}/groups/{groupId}` ## 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 (all optional, at least one field) | Field | Type | Description | |-------|------|-------------| | `name` | string | Heading of the group (1-120 chars). | | `sort` | number | Position, 0-100000. | | `collapsed` | boolean | Start collapsed on the public page. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/status-pages/1/groups/3" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "collapsed": true }' ``` ## Response `200 OK` with the updated group, in the same shape as on [List Status Page Component Groups](/api/status-pages/list-status-page-component-groups). ## Common errors - `400 Bad Request` (`invalidRequestBody`) when the body is empty 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 - `404 Not Found` (`statusPageComponentGroupNotFound`) when the group does not exist on this page ### Update Status Page Design URL: https://docs.uptimeify.io/api/status-pages/update-status-page-design Description: Updates the visual design configuration of a status page. Only the fields you provide are changed. All other settings keep their current values. Requires the role `admin` or `editor`; `readonly` can read the design but not change it. Summary: `PATCH /api/status-pages/:id/design` ## Path Parameter | Parameter | Description | |-----------|-------------| | `id` | Status page ID or `publicId` (UUID) | ## Request Body (all optional) ### Layout | Field | Type | Values | Default | Description | |-------|------|--------|---------|-------------| | `layout` | string | `statusboard` `classic` `cards` `minimal` `sleek` `board` `split` `timeline` `compact` | `statusboard` | Visual layout template. `statusboard` is the default for status pages created from 7 September 2026; pages created before that keep the layout they had. | | `pageWidth` | string | `sm` `md` `lg` `xl` | `lg` | Max content width: sm = 672 px, md = 896 px, lg = 1024 px, xl = 1280 px | ### Colors | Field | Type | Values | Default | Description | |-------|------|--------|---------|-------------| | `colorScheme` | string | `light` `dark` `auto` | `auto` | Color mode. `auto` follows the visitor's system preference. | | `accentColor` | string | hex, e.g. `#6366f1` | `#6366f1` | Brand accent color used for highlights, borders, and gradients | ### Typography & Style | Field | Type | Values | Default | Description | |-------|------|--------|---------|-------------| | `fontFamily` | string | `system` `mono` | `system` | `system` = default sans-serif, `mono` = monospace | | `cardRadius` | string | `none` `md` `xl` | `md` | Card corner radius: none = sharp, md = rounded, xl = pill | ### Header | Field | Type | Values | Default | Description | |-------|------|--------|---------|-------------| | `headerStyle` | string | `simple` `centered` `hero` | `simple` | `simple` = left-aligned, `centered` = centered, `hero` = full gradient banner | | `customTitle` | string | max 120 chars | `""` | Overrides the status page name in the header. Leave empty to use the page name. | | `customSubtitle` | string | max 200 chars | `""` | Optional tagline below the title | ### Display options | Field | Type | Default | Description | |-------|------|---------|-------------| | `showUptimeStats` | boolean | `true` | Show uptime percentage and service counts | | `showServiceUrls` | boolean | `false` | Show the monitored URL below each service name | | `showLastChecked` | boolean | `false` | Show the last check timestamp per service | | `showHistory` | boolean | `true` | Master switch for the incidents and maintenance area | | `historyDays` | integer | `30` | Window of the uptime bars, in days (1-3650). Incidents and maintenance have their own windows, see below. | ### Incidents and maintenance Incidents and maintenance are two separate sections, each with its own switch, its own item count and its own window. | Field | Type | Default | Description | |-------|------|---------|-------------| | `showIncidents` | boolean | `true` | Show the incidents section | | `incidentLimit` | integer | `5` | How many incidents are listed (1-50) | | `incidentDays` | integer | `30` | How far back resolved incidents are listed, in days (1-3650). An open incident is always shown, however old it is. | | `showMaintenance` | boolean | `true` | Show the maintenance section | | `maintenanceLimit` | integer | `5` | How many maintenance windows are listed (1-50) | | `maintenanceDays` | integer | `30` | How far back completed maintenance is listed, in days (1-3650). Announced maintenance is always shown, however far off it is. | `showIncidents` and `showMaintenance` are the same setting as `showRecentIncidents` and `showRecentMaintenance` on the status page itself: writing either of those two through `POST /api/status-pages` or `PATCH /api/status-pages/:id` also updates the design config, so both stay in step. | `showPoweredBy` | boolean | `true` | Show a "Powered by ``" line in the footer. It names your organization's product name and never Uptimeify; with no product name set, nothing is rendered. | ### Custom CSS | Field | Type | Default | Description | |-------|------|---------|-------------| | `customCss` | string | `""` | Your own CSS for the public st… ### Update Status Page Maintenance URL: https://docs.uptimeify.io/api/status-pages/update-status-page-maintenance Description: Changes, reschedules or extends a maintenance. Summary: `PATCH /api/status-pages/maintenances/{id}` Changes only the fields you send. Moving the start of an upcoming maintenance announces it again (with `notifyOnSchedule`); messages for the old times are not sent any more. Extend a running maintenance by moving `scheduledUntil`; to end it now use [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. ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `title` | string | No | - | Shown on the page and in every message (1-200 chars). | | `description` | string\|null | No | - | What happens and what visitors notice (max 5000 chars). | | `scheduledFor` | string | No | - | Start, ISO 8601 with offset (`Z` or `+01:00`); stored and returned in UTC. | | `scheduledUntil` | string | No | - | End, after `scheduledFor`. | | `statusPageIds` | array | No | - | 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 | - | Announce to subscribers when saved, and again when an upcoming start is moved. | | `reminderMinutesBefore` | number\|null | No | - | Remind subscribers this many minutes (5-10080) before the start; `null` sends no reminder. | | `notifyOnStart` | boolean | No | - | Notify subscribers when the maintenance starts. | | `notifyOnComplete` | boolean | No | - | Notify subscribers when it ends. | `statusPageIds` replaces the pages; without `componentIds` they become page-wide. `componentIds` alone replaces the components on the current pages. At least one field is required; unknown fields are rejected. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/status-pages/maintenances/12" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"scheduledUntil": "2026-11-04T00:30:00+01:00"}' ``` ## Response `200 OK` with the whole maintenance, as in [Get Status Page Maintenance](/api/status-pages/get-status-page-maintenance). ## Common errors - `400 Bad Request` (`invalidRequestBody`) when a field is missing, has the wrong type or is unknown; `data.issues` names the field - `400 Bad Request` (`invalidDateRange`) when `scheduledUntil` is not after `scheduledFor` - `400 Bad Request` (`invalidIdentifier`) when an id is neither a number nor a UUID - `400 Bad Request` (`statusPageComponentNotOnPage`) when a component does not belong to one of `statusPageIds` - `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… ### Update Status Page Template URL: https://docs.uptimeify.io/api/status-pages/update-status-page-template Description: Changes fields of a template; null clears an optional field. Summary: `PATCH /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. ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `name` | string | No | - | 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 | No | - | 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`. | At least one field. `statusPageIds` and `componentIds` are checked together: a field you leave out keeps its stored value. 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 PATCH "$BASE_URL/api/status-pages/templates/4" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "body": "We have identified the cause and are working on a fix.", "updateStatus": "identified" }' ``` ## Response `200 OK` with the changed 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 - `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 ### Verify Status Page Domain URL: https://docs.uptimeify.io/api/status-pages/verify-status-page-domain Description: Verifies DNS TXT records for a custom status page domain. Organization-wide: admin only; customer-bound: by the page's ownership class. Summary: `POST /api/status-pages/domains/verify` **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 | Description | |-------|------|----------|-------------| | `domainId` | number | Yes | The domain ID to verify | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/status-pages/domains/verify" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "domainId": 42 }' ``` ## Response (success) ```json { "verified": true, "status": "verified", "domain": { "id": 42, "hostname": "status.deinkunde.com", "status": "verified", "role": "status_page", "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:00: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 - `404 Not found` when the domain does not exist - `400 domainVerificationFailed` when the TXT record was not found. The error data says what we saw, so you can fix the record without guessing: ```json { "statusCode": 400, "statusMessage": "TXT verification failed (token not found)", "data": { "code": "domainVerificationFailed", "recordName": "_verify-status.status.example.com", "expected": "a1b2c3d4e5f6", "lookup": "records", "observed": ["old-token-from-another-tool"], "nameservers": { "zone": "example.com", "hosts": ["ns1.dns-provider.example", "ns2.dns-provider.example"] }, "authoritative": { "nameserver": "ns1.dns-provider.example", "lookup": "records", "observed": ["a1b2c3d4e5f6"] }, "propagation": "propagating" } } ``` `lookup` is `records` (TXT values found, none matches; they are in `observed`, at most 10), `noRecords` (the name exists but has no TXT record), `nxdomain` (the name does not exist), `timeout` or `error` (resolver failure, retry later). `nameservers` is the zone the hostname is delegated in and its authoritative nameservers (`null` if that could not be determined). `authoritative` is what one of those nameservers answered when asked directly for `recordName`, bypassing every cache (`null` if none could be asked; only public addresses are queried). `propagation` reads both answers: `propagating` (your nameserver has the token, our resolver does not see it yet, retry after the TTL), `not_published` (not even your nameserver has it), `unknown` (no nameserver could be asked). The failure is also stored on the domain: every domain response carries it as `lastVerificationError` with `lastVerificationErrorAt` until the next successful verification clears both. - `409 Conflict` (`domainAlreadyClaimed`) when another organization has already verified or activated this hostname. The owner is not disclosed. ### Tags URL: https://docs.uptimeify.io/api/tags Description: Organize your monitors with tags: create, assign, filter, and manage across all monitor types. Summary: Tags let you label any monitor (website, DNS, ICMP, SMTP, SSH, FTP, IMAP/POP) with one or more color-coded tags and then filter any monitor list by tag. Tags are organization-scoped; readonly members can create and use their own tags but cannot see or modify tags created by others. ## Endpoints - [List Tags](/api/tags/list-tags) - [Get Tag](/api/tags/get-tag) - [Create Tag](/api/tags/create-tag) - [Update Tag](/api/tags/update-tag) - [Delete Tag](/api/tags/delete-tag) - [Assign Tag to Monitor](/api/tags/assign-tag) - [Remove Tag from Monitor](/api/tags/remove-tag) - [List Monitor Tags](/api/tags/list-monitor-tags) ### Assign Tag to Monitor URL: https://docs.uptimeify.io/api/tags/assign-tag Description: Assigns an existing tag to a monitor. The caller needs read access to the monitor and visibility of the tag. The operation is idempotent. Summary: `POST /api/monitor-tags` ## Body ```json { "monitorType": "website", "monitorId": 101, "tagId": 1 } ``` - `monitorType` (required): Type of the monitor. One of: `website` | `dns` | `icmp` | `smtp` | `ssh` | `tcp` | `ftp` | `imap_pop` | `customer_domain` | `customer_ip`. Use `customer_domain` for domain (SSL/expiry) monitors and `customer_ip` for DNSBL/blacklist monitors. - `monitorId` (required): Numeric ID of the monitor. - `tagId` (required): Numeric ID of the tag to assign. This operation is **idempotent**: calling it again when the tag is already assigned returns the existing assignment without error. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/monitor-tags" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"monitorType":"website","monitorId":101,"tagId":1}' ``` ## Response ```json { "monitorType": "website", "monitorId": 101, "tagId": 1, "createdAt": "2026-06-29T12:00:00.000Z" } ``` ## Common errors - `400 Bad Request` when `monitorType` is not a supported type - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you do not have read access to the monitor or cannot see the tag - `404 Not Found` when the monitor or tag does not exist ### Create Tag URL: https://docs.uptimeify.io/api/tags/create-tag Description: Creates a new tag in your organization. Readonly members may create tags that are visible only to themselves. Summary: `POST /api/tags` ## Body ```json { "name": "Production", "color": "red" } ``` - `name` (required): Display label for the tag (max 50 characters). - `color` (required): One of the palette keys: `slate` | `red` | `amber` | `green` | `teal` | `blue` | `indigo` | `violet` | `pink` | `gray`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/tags" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"Production","color":"red"}' ``` ## Response ```json { "id": 1, "publicId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": 10, "name": "Production", "color": "red", "createdBy": 42, "createdAt": "2026-06-29T10:00:00.000Z", "updatedAt": "2026-06-29T10:00:00.000Z" } ``` ## Common errors - `400 invalidTagColor` when `color` is not a recognized palette key - `400 Bad Request` when `name` is missing or exceeds the character limit - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization - `403 authorizingUserUnresolved` when the call arrives over an agent session whose authorizing human can no longer be resolved; a tag always records that human as its creator, never the agent, so the tag is not created (see [Error codes and known API pitfalls](/api/error-codes-and-known-pitfalls)) ### Delete Tag URL: https://docs.uptimeify.io/api/tags/delete-tag Description: Deletes a tag and removes it from all monitors it was assigned to. Only the tag owner or an admin may delete a tag. Summary: `DELETE /api/tags/{id}` Path parameter `{id}` is the tag's numeric `id`. Deleting a tag cascades: all monitor-tag assignments for that tag are also removed automatically. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" TAG_ID=1 curl -X DELETE "$BASE_URL/api/tags/$TAG_ID" \ -H "Authorization: Bearer $TOKEN" ``` ## Response Returns `204 No Content` on success. ## Common errors - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you are not the tag owner or an admin - `404 Not Found` when the tag does not exist or is not visible to you ### Get Tag URL: https://docs.uptimeify.io/api/tags/get-tag Description: Returns one tag by numeric id or publicId, in the same shape as an entry of List Tags. Summary: `GET /api/tags/{id}` ## Access Same visibility as [List Tags](/api/tags/list-tags): users limited to customers see tags of their customers and tags they created; a tag outside that answers `404`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/tags/1" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "id": 1, "publicId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": 10, "customerId": null, "name": "Production", "color": "red", "createdBy": "u_abc123", "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-01T08:00:00.000Z", "customer": null, "owner": { "id": "u_abc123", "name": "Ada Admin", "email": "ada@example.com" }, "customers": [] } ``` ## Common errors - `400 Bad Request` when the id is neither a number nor a UUID - `401 Unauthorized` when you are not logged in - `403 Forbidden` when your account has no organization - `404 Not Found` (`tagNotFound`) when the tag does not exist or is not visible to you ### List Monitor Tags URL: https://docs.uptimeify.io/api/tags/list-monitor-tags Description: Returns all tags assigned to a specific monitor. Readonly members see only their own tags. Summary: `GET /api/monitor-tags` ## Query Parameters - `monitorType` (required): Type of the monitor. One of: `website` | `dns` | `icmp` | `smtp` | `ssh` | `tcp` | `ftp` | `imap_pop` | `customer_domain` | `customer_ip`. Use `customer_domain` for domain (SSL/expiry) monitors and `customer_ip` for DNSBL/blacklist monitors. - `monitorId` (required): Numeric ID of the monitor. - `envelope` (string, optional): `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/monitor-tags?monitorType=website&monitorId=101&envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": 1, "publicId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": 10, "name": "Production", "color": "red", "createdBy": 42, "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-01T08: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 - `400 Bad Request` when `monitorType` or `monitorId` is missing or invalid - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you do not have read access to the monitor - `404 Not Found` when the monitor does not exist ### List Tags URL: https://docs.uptimeify.io/api/tags/list-tags Description: Returns all tags visible to the caller. Readonly members see only tags they created themselves. Summary: `GET /api/tags` ## Query Parameters - `organizationId` (optional): Defaults to your session organization. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/tags" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json [ { "id": 1, "publicId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": 10, "name": "Production", "color": "red", "createdBy": 42, "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-01T08:00:00.000Z" }, { "id": 2, "publicId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "organizationId": 10, "name": "Staging", "color": "amber", "createdBy": 42, "createdAt": "2026-06-10T09:00:00.000Z", "updatedAt": "2026-06-10T09:00:00.000Z" } ] ``` ## Common errors - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization ### Remove Tag from Monitor URL: https://docs.uptimeify.io/api/tags/remove-tag Description: Removes a tag assignment from a monitor. The caller must have read access to the monitor. Summary: `DELETE /api/monitor-tags` ## Body ```json { "monitorType": "website", "monitorId": 101, "tagId": 1 } ``` - `monitorType` (required): Type of the monitor. One of: `website` | `dns` | `icmp` | `smtp` | `ssh` | `tcp` | `ftp` | `imap_pop` | `customer_domain` | `customer_ip`. Use `customer_domain` for domain (SSL/expiry) monitors and `customer_ip` for DNSBL/blacklist monitors. - `monitorId` (required): Numeric ID of the monitor. - `tagId` (required): Numeric ID of the tag to remove. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE "$BASE_URL/api/monitor-tags" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"monitorType":"website","monitorId":101,"tagId":1}' ``` ## Response Returns `204 No Content` on success. ## Common errors - `400 Bad Request` when `monitorType` is not a supported type - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you do not have read access to the monitor - `404 Not Found` when the assignment does not exist ### Update Tag URL: https://docs.uptimeify.io/api/tags/update-tag Description: Updates an existing tag's name or color. Only the tag owner or an admin may update a tag. Summary: `PATCH /api/tags/{id}` Path parameter `{id}` is the tag's numeric `id`. ## Body All fields are optional; send only the fields you want to change. ```json { "name": "Critical", "color": "violet" } ``` - `name` (optional): New display label (max 50 characters). - `color` (optional): One of the palette keys: `slate` | `red` | `amber` | `green` | `teal` | `blue` | `indigo` | `violet` | `pink` | `gray`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" TAG_ID=1 curl -X PATCH "$BASE_URL/api/tags/$TAG_ID" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"Critical","color":"violet"}' ``` ## Response ```json { "id": 1, "publicId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": 10, "name": "Critical", "color": "violet", "createdBy": 42, "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-29T11:00:00.000Z" } ``` ## Common errors - `400 invalidTagColor` when `color` is not a recognized palette key - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you are not the tag owner or an admin - `404 Not Found` when the tag does not exist or is not visible to you ### Users URL: https://docs.uptimeify.io/api/users Description: Manage users within your organization. Summary: ## Endpoints - [List Users](/api/users/list-users) - [Create User](/api/users/create-user) - [Get User](/api/users/get-user) - [Update User](/api/users/update-user) - [Delete User](/api/users/delete-user) - [Reset User MFA](/api/users/reset-mfa) ### Change User Email URL: https://docs.uptimeify.io/api/users/change-email Description: Starts a change of another user's sign-in email. It takes effect once the user confirms it from the new address. Summary: `POST /api/users/:id/email-change` An organization admin can change the sign-in email of a member of their own organization, a global admin of any user. The address does not change right away: a confirmation link is mailed to the new address, valid for 24 hours, and the change takes effect once it is opened. Until then the user keeps signing in with the current address. Opening the link signs nobody in. Once the change is confirmed, the old address receives a notice naming the new address and who requested it. A new request replaces an earlier one that is still open, so only the latest link works. **API tokens cannot call this endpoint.** It requires a real, logged-in user session. If the calling admin has two-step verification, they confirm their second factor first (`403 mfa_step_up_required`: enter the code in the dashboard dialog, then repeat the request). Your own address is changed in your profile instead, which asks for your password. ## Request Body | Field | Type | Required | Description | | --- | --- | --- | --- | | `newEmail` | string | yes | The new sign-in email. Stored in lower case. | ## Example (cURL) Call this endpoint from an authenticated browser session (the admin's own login session cookie), not with an API token: ```bash BASE_URL="https://uptimeify.io" curl -X POST "$BASE_URL/api/users/user_123/email-change" \ -H "Cookie: better-auth.session_token=" \ -H "Content-Type: application/json" \ -d '{"newEmail": "jane.doe@example.com"}' ``` ## Response ```json { "ok": true, "pendingEmail": "jane.doe@example.com" } ``` ## Common errors - `401 unauthorized` when you are not authenticated - `403 nonUserSessionForbidden` when called with an API token or agent access token - `403 mfa_step_up_required` when your account has two-step verification and you have not confirmed it in the last five minutes - `403 forbidden` when you are not an organization admin or global admin - `403 globalUserProtected` when the target is a platform account (global admin or supporter) and you are not a global admin - `404 userNotFound` when the user does not exist or belongs to another organization - `400 userSelfChangeForbidden` when `:id` is your own user; change your address in your profile - `400 emailUnchanged` when the new address is the current one - `400 emailAlreadyExists` when another member of your organization already uses the address. An address held by an account outside your organization is not named: the request answers like a free one and no link is sent - `502 emailSendFailed` when the confirmation link could not be sent; the address is unchanged ### Create User URL: https://docs.uptimeify.io/api/users/create-user Description: Creates a new user in the organization. Summary: `POST /api/users` ## Request Body ```json { "email": "jane@deinkunde.com", "firstName": "Jane", "lastName": "Doe", "role": "editor", // "admin", "editor", "readonly" or "responder" "language": "en", // Optional: "de", "en" or "da" "customerIds": ["11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222"] // Optional: Limit access to specific customers via public IDs } ``` Notes: - `customerIds` accepts customer public IDs and legacy numeric IDs. - `customerIds` is only allowed for `role: "readonly"`. Sending a non-empty `customerIds` with any other role returns `400` with `data.code: "customerIdsReadonlyOnly"` (it used to be ignored silently, which created an organization-wide user). - Public IDs are the preferred format for new integrations. - `language` is optional: the new user's starting language for the dashboard, e-mails and text messages (`de`, `en` or `da`). It also decides the language of the invitation e-mail. Omitted, the user gets the language of the one customer they are invited for (`readonly` with a single customer), otherwise the organization's language. The user can change it later in their profile. Any other value is rejected with `400`. - There is no password field: the user receives an invitation e-mail and sets their own password. ## Response Returns the created user object. See [Error Codes](/api/error-codes-and-known-pitfalls) for error responses. ### Delete User URL: https://docs.uptimeify.io/api/users/delete-user Description: Removes a user from the organization. Summary: `DELETE /api/users/:id` ## Guards - You cannot delete yourself. - The last active admin of an organization cannot be deleted. Promote another user to `admin` first. - A user who is a global admin or global supporter can only be deleted by a global admin. ## Common errors - `400 Bad Request` with `data.code: "selfDeletionNotAllowed"` when the target is your own account - `400 Bad Request` with `data.code: "lastAdminProtected"` when the user is the organization's last active admin - `403 Forbidden` with `data.code: "globalUserProtected"` when a tenant admin tries to delete a global admin or global supporter - `404 Not Found` when the user does not exist in your organization ## Response ```json { "success": true } ``` ### Get User URL: https://docs.uptimeify.io/api/users/get-user Description: Returns the details of a single user the caller is allowed to see. Summary: `GET /api/users/:id` ## Who may read which user Two conditions apply, and both have to hold. First, the caller needs an administrative role: an organization admin, a global admin, or a token that acts with admin privileges. Any other session is refused with `403`. Second, the answer is narrowed by the caller's customer scope, the same scope that governs [List Users](/api/users/list-users), `/api/customers` and the monitor endpoints. A user is never "owned" by a customer, the link is the customer access assignment, so visibility is derived from it: | Caller | Users readable | | --- | --- | | Organization admin, global admin, organization-wide API token | Every user of the organization (a global admin also beyond it) | | Customer-scoped API token, or a session restricted to specific customers | Only users assigned to at least one of the caller's customers, plus the caller | A user outside that scope answers `404 userNotFound`, the same status as a user that does not exist: an invisible user and a nonexistent one are deliberately not distinguishable. The `customerAccess` array is reduced to the customers the caller is scoped to. A colleague who also works for other customers does not disclose them here. Cross-organization access is impossible except for a global admin, the organization boundary is applied before the customer scope. ## Response ```json { "id": "A7QJr8SOjsnTst1n9YQSYxim1GeEPht7", "email": "max@deinkunde.com", "name": "Max Mustermann", "firstName": "Max", "lastName": "Mustermann", "image": null, "role": "admin", "language": "en", "isActive": true, "createdAt": "2026-01-01T00:00:00.000Z", "customerAccess": [ { "customerId": 42, "customerName": "Beispiel GmbH" } ] } ``` `language` is the mail language of the login (`de`, `en` or `da`); `null` means the organization's language. ## Common errors | Status | `data.code` | Meaning | | --- | --- | --- | | 401 | `unauthorized` | No valid session or token. | | 403 | `forbidden` | The caller is not an admin. | | 400 | `userIdRequired` | No user id in the path. | | 400 | `organizationIdRequired` | The session carries no organization. | | 404 | `userNotFound` | No such user, or the user is outside the caller's organization or customer scope. | ### List Users URL: https://docs.uptimeify.io/api/users/list-users Description: Lists the users of the organization that the caller is allowed to see. Summary: `GET /api/users` ## Who sees which users The response is narrowed by the caller's customer scope, the same scope that governs `/api/customers`, `/api/incidents` and the monitor endpoints. A user is never "owned" by a customer, the link is the customer access assignment, so visibility is derived from it: | Caller | Users returned | | --- | --- | | Organization admin, global admin, global supporter, organization-wide API or agent token | Every user of the organization (unchanged) | | Editor without customer assignments | Every user of the organization | | Readonly user, editor with customer assignments, customer-scoped API token, customer-bound agent token | Only users assigned to at least one of the caller's customers, plus the caller | | Caller restricted to no customer at all (for example the IM-only `responder` role) | Empty list | Two further points for a customer-scoped caller: - The `customerAccess` array of every returned user is reduced to the customers the caller is scoped to. A colleague who also works for other customers does not disclose them here. - `limits` is still returned. Seat allowances are organization-level plan facts, and `currentSeats` counts the users actually contained in the response. Cross-organization access is impossible in every case, the organization boundary is applied before the customer scope. ## Response ```json { "users": [ { "id": "A7QJr8SOjsnTst1n9YQSYxim1GeEPht7", "email": "max@deinkunde.com", "name": "Max Mustermann", "firstName": "Max", "lastName": "Mustermann", "image": null, "role": "admin", "language": "en", "isActive": true, "createdAt": "2026-01-01T00:00:00.000Z", "customerAccess": [ { "customerId": 42, "customerName": "Beispiel GmbH" } ] } ], "limits": { "maxSeats": null, "currentSeats": 1, "remainingSeats": null } } ``` `language` is the mail language of the login (`de`, `en` or `da`); `null` means the organization's language. **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`, one page with every user the caller may see, without `limits`. Without the parameter the endpoint still answers the current form (`{ users, limits }`), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. ## Common errors | Status | `data.code` | Meaning | | --- | --- | --- | | 401 | `unauthorized` | No valid session or token. | | 400 | `organizationIdRequired` | The session carries no organization. | ### Reset User MFA URL: https://docs.uptimeify.io/api/users/reset-mfa Description: Clears another user's two-step verification, so they can set it up again from scratch. Summary: `POST /api/users/:id/mfa/reset` An organization admin (or global admin) can force-reset another user's two-step verification. This deletes the user's stored second factor and turns `twoFactorEnabled` off for their account, it does not enroll a new factor. The user is emailed a notification and must set up two-step verification again the next time it is required. You cannot reset your own second factor through this endpoint. Removing your own factor goes through account security settings instead, and requires your password. **API tokens cannot call this endpoint.** It requires a real, logged-in user session (an organization admin or global admin), an `Authorization: Bearer` API token is always rejected, even an organization-scoped one with admin-level access. This applies to agent access tokens too. A leaked token must never be able to strip an organization's MFA protection by resetting members' factors one by one. ## Request Body None. ## Example (cURL) Call this endpoint from an authenticated browser session (the admin's own login session cookie), not with an API token: ```bash BASE_URL="https://uptimeify.io" curl -X POST "$BASE_URL/api/users/user_123/mfa/reset" \ -H "Cookie: better-auth.session_token=" \ -H "Accept: application/json" ``` ## Response ```json { "ok": true } ``` ## Common errors - `401 unauthorized` when you are not authenticated - `403 nonUserSessionForbidden` when called with an API token or agent access token instead of a real user session, see above - `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 userNotFound` when the target `:id` does not resolve to a user - `403 insufficientPermissions` when the caller may not reset this user's second factor, see below Permission rules (`data.code: insufficientPermissions`): - You can never reset your own second factor through this endpoint. - Global admins can reset any user. - Global supporters (read-only across all organizations) can never reset a user. - Organization admins can reset users in their own organization only; the target must belong to the same organization as the caller. - Regular (non-admin) users can never reset another user's second factor. ### Update User URL: https://docs.uptimeify.io/api/users/update-user Description: Updates the details and permissions of a user. Summary: `PATCH /api/users/:id` ## Request Body ```json { "firstName": "Jane", "lastName": "Smith", "role": "admin", "isActive": true, "language": "en", "customerIds": ["11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222"] // Update the list of assigned customers via public IDs } ``` Notes: - `customerIds` accepts customer public IDs and legacy numeric IDs. - Public IDs are the preferred format for new integrations. - `firstName` and `lastName` are limited to 100 characters, `role` must be one of `admin`, `editor`, `readonly`, `responder`, `customerIds` holds at most 500 entries. - `language` is optional: the user's language for the dashboard, e-mails and text messages, `de`, `en` or `da` (the same values as [Create User](/api/users/create-user)). Any other value is rejected with `400`. The change is recorded in the audit log with the old and new value. - The global platform flags (`isGlobalAdmin`, `isGlobalSupporter`) cannot be set through this endpoint; they are ignored if sent. ## Guards - You cannot deactivate yourself or change your own role. - The last active admin of an organization cannot be demoted or deactivated. Promote another user to `admin` first. - A user who is a global admin or global supporter can only be modified by a global admin. ## Common errors - `400 Bad Request` when the body fails validation (unknown field type, string too long, `customerIds` not an array) - `400 Bad Request` with `data.code: "invalidRole"` when `role` is not one of the allowed values - `400 Bad Request` with `data.code: "userSelfChangeForbidden"` when you try to deactivate yourself or change your own role - `400 Bad Request` with `data.code: "lastAdminProtected"` when the change would leave the organization without an active admin - `403 Forbidden` with `data.code: "globalUserProtected"` when a tenant admin tries to modify a global admin or global supporter - `404 Not Found` when the user does not exist in your organization ## Response Returns the updated user object as `{ success, user }`, `user` in the same shape as [Get User](/api/users/get-user), including `language`. See [Error Codes](/api/error-codes-and-known-pitfalls) for error responses. ### Configurations URL: https://docs.uptimeify.io/api/website-configuration Description: Manage advanced monitoring settings for your websites. Summary: ## Authentication All examples assume a bearer token: ```bash BASE_URL="https://uptimeify.io" TOKEN="" ``` ## Check Configuration ### Update Check Settings `PATCH /api/websites/:websiteId/check-config` Configure which aspects of the website should be monitored. #### Request Body ```json { "checkSslEnabled": true, "checkHttpsRedirectEnabled": true, "checkStatusEnabled": true, "checkSizeEnabled": true, "checkResponseTimeEnabled": true, "checkKeywordEnabled": false, "checkDomainExpiryEnabled": true, "minPageSize": 1024, "maxPageSize": 5242880 } ``` Example (cURL): ```bash curl -X PATCH \ "$BASE_URL/api/websites/101/check-config" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"checkSslEnabled":true,"checkHttpsRedirectEnabled":true,"checkStatusEnabled":true,"checkSizeEnabled":true,"checkResponseTimeEnabled":true,"checkKeywordEnabled":false}' ``` ## Alerting Configuration Alerting-related defaults and feature flags are configured via **organization package configs**. See: - [List Package Configs](/api/organization/list-package-configs) - [Upsert Package Config](/api/organization/upsert-package-config) - [Delete Package Config](/api/organization/delete-package-config) ## Notification Channels ## Maintenance Windows ### List Maintenance Windows `GET /api/maintenance-windows?websiteId=:websiteId` ### Get Maintenance Window `GET /api/maintenance-windows/:id` ### Create Maintenance Window `POST /api/maintenance-windows` ### Update Maintenance Window `PATCH /api/maintenance-windows/:id` ### Delete Maintenance Window `DELETE /api/maintenance-windows/:id` ### Check Maintenance (Website) `GET /api/maintenance-windows/check/:websiteId` ### Check Maintenance (Batch) `POST /api/maintenance-windows/check/batch` ## Endpoints - [Update Check Settings](/api/website-configuration/update-check-settings) - [List Maintenance Windows](/api/website-configuration/list-maintenance-windows) - [Get Maintenance Window](/api/website-configuration/get-maintenance-window) - [Create Maintenance Window](/api/website-configuration/create-maintenance-window) - [Update Maintenance Window](/api/website-configuration/update-maintenance-window) - [Delete Maintenance Window](/api/website-configuration/delete-maintenance-window) - [Check Maintenance (Website)](/api/website-configuration/check-maintenance-window) - [Check Maintenance (Batch)](/api/website-configuration/check-maintenance-window-batch) ### Check Maintenance (Website) URL: https://docs.uptimeify.io/api/website-configuration/check-maintenance-window Description: Checks if a website is currently in an active maintenance window. Summary: `GET /api/maintenance-windows/check/:websiteId` This endpoint requires authentication via browser session or API token. ## Parameters - `websiteId` (Path, required): Internal numeric website ID or `websitePublicId` (UUID). ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" API_TOKEN="wsm_your_real_api_token" curl -X GET "$BASE_URL/api/maintenance-windows/check/cd11a84d-96a2-41aa-a957-b1db8ee01b72" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "inMaintenance": true, "activeWindows": [ { "id": 5, "name": "Weekly maintenance", "startTime": "2026-02-25T02:00:00.000Z", "endTime": "2026-02-25T04:00:00.000Z", "description": "Planned downtime" } ] } ``` ## Common errors - `401 Unauthorized` when no valid session or API token is sent - `403 Forbidden` when the website is outside the allowed customer/organization scope - `400 Invalid Website identifier` when `:websiteId` is neither a positive integer ID nor a UUID - `404 Website not found` when the provided `websitePublicId` does not resolve to a website ### Check Maintenance (Batch) URL: https://docs.uptimeify.io/api/website-configuration/check-maintenance-window-batch Description: Batch-check multiple websites for active maintenance windows. Summary: `POST /api/maintenance-windows/check/batch` This endpoint requires authentication via browser session or API token. ## Request Body ```json { "websiteIds": [101, "cd11a84d-96a2-41aa-a957-b1db8ee01b72", 103] } ``` ### Fields - `websiteIds` ((number|string)[], required): numeric website IDs or `websitePublicId` UUIDs ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" API_TOKEN="wsm_your_real_api_token" curl -X POST "$BASE_URL/api/maintenance-windows/check/batch" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"websiteIds":[101,"cd11a84d-96a2-41aa-a957-b1db8ee01b72",103]}' ``` ## Example Response ```json { "results": { "101": { "inMaintenance": true, "activeWindows": [ { "id": 5, "name": "Weekly maintenance", "startTime": "2026-02-25T02:00:00.000Z", "endTime": "2026-02-25T04:00:00.000Z", "description": "Planned downtime" } ] }, "cd11a84d-96a2-41aa-a957-b1db8ee01b72": { "inMaintenance": false, "activeWindows": [] } } } ``` ## Common errors - `400 websiteIds array required` when `websiteIds` is missing/empty - `400 All websiteIds must be valid identifiers` when any entry is neither a positive integer ID nor a UUID - `401 Unauthorized` when no valid session or API token is sent - `403 Forbidden` when at least one website is outside the allowed customer/organization scope - `404 Website not found` when a provided `websitePublicId` does not resolve to a website ### Create Maintenance Window URL: https://docs.uptimeify.io/api/website-configuration/create-maintenance-window Description: Creates a new maintenance window. Summary: `POST /api/maintenance-windows` Important: You must provide **exactly one** target ID (e.g. `websiteId` *or* `icmpMonitorId`, `smtpMonitorId`, `sshMonitorId`, `tcpMonitorId`, `ftpMonitorId`, `imapPopMonitorId`). All target IDs and `customerId` accept either the internal numeric ID or the matching public UUID. ## Authentication Requires a valid session or API token. - Header: `Authorization: Bearer ` Note: Global supporter users are not allowed to create maintenance windows (`403`). Read-only users are allowed. ## Request Body ```json { "websiteId": "521e3338-4597-4d1d-8eeb-dc56d271e71c", "name": "Server Upgrade", "description": "Planned downtime", "startTime": "2026-02-25T02:00:00.000Z", "endTime": "2026-02-25T04:00:00.000Z", "isRecurring": true, "recurrencePattern": { "frequency": "weekly", "intervalCount": 1, "daysOfWeek": [1] }, "isActive": true } ``` ### Fields Target (exactly one required): - `websiteId` (number|string) - `icmpMonitorId` (number|string) - `smtpMonitorId` (number|string) - `sshMonitorId` (number|string) - `tcpMonitorId` (number|string) - `ftpMonitorId` (number|string) - `imapPopMonitorId` (number|string) - `customerId` (number|string, optional) Identifier rule: Internal numeric IDs or public UUIDs are accepted. Other fields: - `name` (string, required) - `description` (string, optional) - Max length: 2000 - If omitted (or empty), it is stored as `null`. - `startTime` (string/date, required) - `endTime` (string/date, required) - Must be after `startTime`. - `isRecurring` (boolean, optional) - Default: `false` - `recurrencePattern` (object, optional) - Stored as JSON. - Typical keys include `frequency`, `intervalCount`, `daysOfWeek`, `dayOfMonth`, `endRecurrenceDate`. - `isActive` (boolean, optional) - Default: `true` - `timezone` (string, optional) - Default: `"UTC"` - 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. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST \ "$BASE_URL/api/maintenance-windows" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"websiteId":"521e3338-4597-4d1d-8eeb-dc56d271e71c","name":"Server Upgrade","description":"Planned downtime","startTime":"2026-02-25T02:00:00.000Z","endTime":"2026-02-25T04:00:00.000Z","isRecurring":true,"recurrencePattern":{"frequency":"weekly","intervalCount":1,"daysOfWeek":[1]},"isActive":true}' ``` ## Example Response ```json { "id": 5, "websiteId": 101, "icmpMonitorId": null, "smtpMonitorId": null, "sshMonitorId": null, "tcpMonitorId": null, "ftpMonitorId": null, "imapPopMonitorId": null, "customerId": 12, "name": "Server Upgrade", "description": "Planned downtime", "startTime": "2026-02-25T02:00:00.000Z", "endTime": "2026-02-25T04:00:00.000Z", "isRecurring": true, "recurrencePattern": { "frequency": "weekly", "intervalCount": 1, "daysOfWeek": [1] }, "isActive": true, "timezone": "UTC", "targets": [{ "type": "website", "id": 101, "name": "Shop", "publicId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }], "tags": [], "createdBy": "", "createdAt": "2026-02-20T10:00:00.000Z", "updatedAt": "2026-02-20T10:00:00.000Z" } ``` **Targets and tags:** the response carries `targets` (`{ type, id, name, publicId }[]`, the window's monitors) and `tags` (`{ id, publicId, name, color }[]`) in the same shape as [Get Maintenance Window](/api/website-configuration/get-maintenance-window), so a client can read back what it stored without a second request. **Deprecated field:** until 2027-01-18 responses still carry `recurrencePattern.interval` next to `recurrencePattern.intervalCount` and request bodies still accept it. Send `intervalCount`; bo… ### Delete Maintenance Window URL: https://docs.uptimeify.io/api/website-configuration/delete-maintenance-window Description: Deletes a maintenance window. Summary: `DELETE /api/maintenance-windows/:id` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` Note: Global supporter users are not allowed to delete maintenance windows (`403`). Read-only users are allowed. ## Parameters - `id` (Path, required): Maintenance window ID. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE \ "$BASE_URL/api/maintenance-windows/5" \ -H "Authorization: Bearer $TOKEN" ``` ## Example Response ```json { "success": true } ``` ## Common Errors - `400 Invalid maintenance window ID` if `:id` is invalid - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access - `404 Maintenance window not found` if the maintenance window does not exist ### Get Maintenance Window URL: https://docs.uptimeify.io/api/website-configuration/get-maintenance-window Description: Returns a single maintenance window by ID (including its target relation). Summary: `GET /api/maintenance-windows/:id` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` Note (API token scope): If you use a customer-scoped API token, the window must belong to that customer. ## Parameters - `id` (Path, required): Maintenance window ID. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/maintenance-windows/5" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "id": 5, "websiteId": 101, "icmpMonitorId": null, "smtpMonitorId": null, "sshMonitorId": null, "tcpMonitorId": null, "ftpMonitorId": null, "imapPopMonitorId": null, "customerId": 12, "name": "Weekly maintenance", "description": "Planned downtime", "startTime": "2026-02-25T02:00:00.000Z", "endTime": "2026-02-25T04:00:00.000Z", "isRecurring": true, "recurrencePattern": { "frequency": "weekly", "intervalCount": 1, "daysOfWeek": [1] }, "isActive": true, "timezone": "UTC", "createdBy": "", "createdAt": "2026-02-20T10:00:00.000Z", "updatedAt": "2026-02-20T10:00:00.000Z", "website": { "id": 101, "url": "https://deinkunde.com" } } ``` Note: Depending on the target, the response may also include one of these relations: `icmpMonitor`, `smtpMonitor`, `sshMonitor`, `tcpMonitor`, `ftpMonitor`, `imapPopMonitor`. Nested `customer` objects are not returned. `targets` lists every monitor the window covers as `{ type, id, name, publicId }` (same shape as the list endpoint); `tags` lists the attached tags. A window with neither covers all monitors of its customer. **Deprecated field:** `recurrencePattern.interval` is still sent next to `recurrencePattern.intervalCount` until it is removed on 2027-01-18. Read `intervalCount`. ## Common errors - `400 Invalid maintenance window ID` when `:id` is invalid - `404 Maintenance window not found` when the window does not exist - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the target/customer - `500 Maintenance window target is missing` if the window has no valid target ### List Maintenance Windows URL: https://docs.uptimeify.io/api/website-configuration/list-maintenance-windows Description: Returns maintenance windows scoped to your organization by default. Summary: `GET /api/maintenance-windows` You can filter by a specific target (e.g. `websiteId`) or by customer/organization. ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Query Parameters - `websiteId` (optional): returns every window that applies to this website: windows targeting it directly, multi-target and tag windows that include it, and customer-wide windows of its customer (no explicit targets or tags). These windows may carry `websiteId: null`. - `customerId` (optional) - `organizationId` (optional, defaults to the website's organization when `websiteId` is set, otherwise 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. - `activeOnly` (optional): set to `true` to only return active windows - Target filters (optional, exactly one is typically used when narrowing down): - `icmpMonitorId`, `smtpMonitorId`, `sshMonitorId`, `tcpMonitorId`, `ftpMonitorId`, `imapPopMonitorId` Note: When `websiteId` is provided, access is enforced for that website. Note (API token scope): If you use a customer-scoped API token, results are restricted to that customer. Providing a different `customerId` returns `403`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET \ "$BASE_URL/api/maintenance-windows?websiteId=101" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json [ { "id": 5, "websiteId": 101, "icmpMonitorId": null, "smtpMonitorId": null, "sshMonitorId": null, "tcpMonitorId": null, "ftpMonitorId": null, "imapPopMonitorId": null, "customerId": 12, "customerName": "Acme Corp", "name": "Weekly maintenance", "description": "Planned downtime", "startTime": "2026-02-25T02:00:00.000Z", "endTime": "2026-02-25T04:00:00.000Z", "isRecurring": true, "recurrencePattern": { "frequency": "weekly", "intervalCount": 1, "daysOfWeek": [1] }, "isActive": true, "timezone": "UTC", "createdBy": "", "createdAt": "2026-02-20T10:00:00.000Z", "updatedAt": "2026-02-20T10:00:00.000Z", "website": { "id": 101, "url": "https://deinkunde.com" } } ] ``` Note: The list endpoint only includes the `website` relation (when `websiteId` is set). It does not include nested `customer` objects or monitor relations. A lightweight top-level `customerName` is included for display/filtering. **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` if you are not authenticated - `403 Forbidden` if you do not have access ### Update Check Settings URL: https://docs.uptimeify.io/api/website-configuration/update-check-settings Description: Configure which aspects of the website should be monitored. Summary: `PATCH /api/websites/:websiteId/check-config` Switching `checkKeywordEnabled` on while the website has no `searchTerm`, or `checkSizeEnabled` while neither `minPageSize` nor `maxPageSize` is set, answers `400 checkRequiresValue`: without them these checks measure nothing. `searchTerm` is not part of this body, so the stored one counts; for the page-size bounds the body counts, otherwise the stored value. A check that is already running is turned off when its value is missing. ## Request Body ```json { "checkSslEnabled": true, "checkHttpsRedirectEnabled": true, "checkStatusEnabled": true, "checkSizeEnabled": true, "checkResponseTimeEnabled": true, "checkKeywordEnabled": false, "checkDomainExpiryEnabled": true, "minPageSize": 1024, "maxPageSize": 5242880 } ``` Your organization's package may forbid a given check. A `true` that switches such a check on answers `403` with `data.code` `checkNotInPackage` and `data.check` naming the field; the package is checked before the missing value. A `true` for a check that is already running on this website (or was never set) is accepted even when the package now forbids it, and the package never turns it off. `false` is always accepted. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH \ "$BASE_URL/api/websites/101/check-config" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"checkSslEnabled":true,"checkHttpsRedirectEnabled":true,"checkStatusEnabled":true,"checkSizeEnabled":true,"checkResponseTimeEnabled":true,"checkKeywordEnabled":false,"checkDomainExpiryEnabled":true,"minPageSize":1024,"maxPageSize":5242880}' ``` ## Example Response ```json { "success": true } ``` ## Common errors - `400 Invalid website ID` when `:websiteId` is invalid - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you do not have write access to the website - `403 Forbidden` (`checkNotInPackage`) when an explicit `true` switches on a check the customer's package forbids (`data.check` names it) - `400 Bad Request` (`checkRequiresValue`) when `checkKeywordEnabled: true` meets a website without `searchTerm`, or `checkSizeEnabled: true` has neither `minPageSize` nor `maxPageSize` (`data.check`, `data.field`) - `404 Website not found` when the website does not exist ### Update Maintenance Window URL: https://docs.uptimeify.io/api/website-configuration/update-maintenance-window Description: Updates an existing maintenance window. Summary: `PATCH /api/maintenance-windows/:id` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` Note: Global supporter users are not allowed to update maintenance windows (`403`). Read-only users are allowed. ## Parameters - `id` (Path, required): Maintenance window ID. ## Request Body All fields are optional. ```json { "name": "Server Upgrade (updated)", "description": null, "startTime": "2026-02-25T02:00:00.000Z", "endTime": "2026-02-25T04:00:00.000Z", "isRecurring": true, "recurrencePattern": { "frequency": "weekly", "intervalCount": 1, "daysOfWeek": [1] }, "isActive": true, "timezone": "Europe/Berlin" } ``` Notes: - You cannot change the target IDs (`websiteId`, `icmpMonitorId`, ...). Only the window fields can be updated. - `description` can be set to `null` to clear it. - If you update `startTime` and/or `endTime`, `endTime` must be after `startTime`. - `timezone` (string, optional): the IANA zone 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. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH \ "$BASE_URL/api/maintenance-windows/5" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"Server Upgrade (updated)","description":null,"startTime":"2026-02-25T02:00:00.000Z","endTime":"2026-02-25T04:00:00.000Z","isRecurring":true,"recurrencePattern":{"frequency":"weekly","intervalCount":1,"daysOfWeek":[1]},"isActive":true}' ``` ## Example Response ```json { "id": 5, "websiteId": 101, "icmpMonitorId": null, "smtpMonitorId": null, "sshMonitorId": null, "tcpMonitorId": null, "ftpMonitorId": null, "imapPopMonitorId": null, "customerId": 12, "name": "Server Upgrade (updated)", "description": null, "startTime": "2026-02-25T02:00:00.000Z", "endTime": "2026-02-25T04:00:00.000Z", "isRecurring": true, "recurrencePattern": { "frequency": "weekly", "intervalCount": 1, "daysOfWeek": [1] }, "isActive": true, "timezone": "Europe/Berlin", "targets": [{ "type": "website", "id": 101, "name": "Shop", "publicId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }], "tags": [], "createdBy": "", "createdAt": "2026-02-20T10:00:00.000Z", "updatedAt": "2026-02-21T11:00:00.000Z" } ``` **Targets and tags:** the response carries `targets` (`{ type, id, name, publicId }[]`, the window's monitors) and `tags` (`{ id, publicId, name, color }[]`) in the same shape as [Get Maintenance Window](/api/website-configuration/get-maintenance-window), so a client can read back what it stored without a second request. **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 - `400 Invalid maintenance window ID` if `:id` is invalid - `400 End time must be after start time` if you update the time range to an invalid value - `400` (validation) if `timezone` is a raw UTC offset or not a zone name the runtime recognizes - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access - `404 Maintenance window not found` if the maintenance window does not exist ### Website Management URL: https://docs.uptimeify.io/api/websites Description: Manage monitored websites. Summary: Path-based website endpoints use `websitePublicId` UUIDs. ## Endpoints - [List Websites](/api/websites/list-websites) - [Create Website](/api/websites/create-website) - [Get Website](/api/websites/get-website) - [Get Website Details](/api/websites/get-website-details) - [Update Website](/api/websites/update-website) - [Change Status](/api/websites/change-status) - [Delete Website](/api/websites/delete-website) - [Rotate Heartbeat Token](/api/websites/rotate-heartbeat-token) ### Change Website Status URL: https://docs.uptimeify.io/api/websites/change-status Description: Changes the monitoring status of a website. Summary: `PATCH /api/websites/:websitePublicId` There is no dedicated `.../status` endpoint. Status changes are part of `PATCH /api/websites/:websitePublicId`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/websites/9a3d4d4d-7a4b-4f37-a9df-2a6f6d9d7a10" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "status": "maintenance" }' ``` ## Request Body ```json { "status": "active" } ``` Allowed values: - `active` - `inactive` (you may also send `paused`, it will be mapped to `inactive`) - `maintenance` ## Response Returns the updated website record. ## Common errors - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot write to the website - `403 Active website limit reached...` when switching to `active` would exceed the customer/package limit ### Create Website URL: https://docs.uptimeify.io/api/websites/create-website Description: Creates a new website monitor for a customer. Summary: `POST /api/websites` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/websites" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "customerId": "059e1469-0f05-4c93-bd4d-89c45bb2afd9", "name": "New Landing Page", "url": "https://landing.deinkunde.com", "monitoringType": "combined", "checkInterval": 5 }' ``` ## Example (cURL): Connect target Measures the origin behind a WAF/CDN by connecting to a different host than the one in `url`, while the URL, path, `Host` header and TLS SNI stay the public hostname: ```bash curl -X POST "$BASE_URL/api/websites" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"customerId":"...","name":"Shop (Origin)","url":"https://shop.example.com","connectHost":"origin.example.com","connectTlsInsecure":true}' ``` ## Request Body ### Core fields | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `customerId` | number\|string | Yes | - | Customer public ID (preferred) or legacy numeric ID | | `name` | string | Yes | - | Display name (1-255 chars) | | `url` | string | Yes* | - | URL to monitor (max 2048 chars). Required for `combined`, `http_status`, `ssl_check` and `dns`; optional for `heartbeat` and `playwright`. HTTP monitors need a full URL including protocol; DNS monitors take a bare hostname (no protocol, no path). | | `monitoringType` | string | No | `combined` | `combined`, `http_status`, `ssl_check`, `playwright`, `heartbeat`, `dns` | | `status` | string | No | `active` | `active`, `inactive`, `maintenance` (`paused` accepted, mapped to `inactive`) | | `checkInterval` | number | No | 30 | Check interval in minutes. Actively scheduled monitors accept 1-1440 (24 hours); `heartbeat` monitors accept 1-43200 (30 days), because the value is the expected ping interval rather than a polling rate. The minimum your organization may set depends on the package. | | `timeoutSeconds` | number | No | 30 | Request timeout in seconds (1-60) | | `expectedStatusCodes` | string | No | `200,301,302` | Comma-separated expected HTTP status codes. Digits, commas and spaces only. | | `allowedCheckCountryCodes` | string[]\|null | No | org default | Array of 2-letter country codes to restrict monitoring locations | | `searchTerm` | string\|null | No | null | Keyword to search for in response body (max 255 chars) | | `customFields` | object\|null | No | null | Custom field values as key-value pairs | | `allowPaidQuotaUpgrade` | boolean | No | `false` | Consent to a PAID quota upgrade. Only relevant when the organization is at its monitor quota AND has automatic quota upgrading switched on: an agent (MCP) call then needs this set to `true`, otherwise it is refused with `paidQuotaUpgradeNotAuthorized` and the message names the tier and the price. Any other caller is unaffected and the field is ignored - a person in the dashboard sees the price, a model does not. It is never stored and never part of duplicate detection. | | `managementType` | string | No | `managed` | Ownership class: `managed` or `self_service`: see [Managed vs. Self-Service](/monitoring/managed-vs-self-service). Only organization admins may choose it; customer-scoped creators always get `self_service` (requires `allowSelfService` and free quota). | ### Authentication | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `authMode` | string | No | `none` | `none`, `authorization_header`, `basic` | | `authorizationHeader` | string\|null | No | null | Required when `authMode` is `authorization_header` (1-4096 chars). Encrypted at rest. | | `basicAuthUsername` | string\|null | No | null | Required when `authMode` is `basic` (1-255 chars) | | `basicAuthPassword` | string\|null | No | null | Required when `authMode` is `basic` (1-4096 chars). Encrypted at rest. | ### HTTP Request Configuration | Field | Type… ### Delete Website URL: https://docs.uptimeify.io/api/websites/delete-website Description: Irrevocably removes a website and its monitoring history. Summary: `DELETE /api/websites/:websitePublicId` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE "$BASE_URL/api/websites/9a3d4d4d-7a4b-4f37-a9df-2a6f6d9d7a10" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "success": true } ``` ## Common errors - `400 Website public ID (UUID) required` when `:websitePublicId` is invalid - `401 Unauthorized` when you are not logged in - `500 Failed to delete website` on server errors ## 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 Website URL: https://docs.uptimeify.io/api/websites/get-website Description: Returns a single website (basic/sanitized). Sensitive fields like encrypted credentials are removed. Summary: `GET /api/websites/:websitePublicId` If you need the full “mega” representation (including additional computed/status fields), use: - `GET /api/websites/:websitePublicId/details` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/websites/9a3d4d4d-7a4b-4f37-a9df-2a6f6d9d7a10" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "id": 101, "organizationId": 1, "customerId": 1, "name": "Main Marketing Site", "url": "https://deinkunde.com", "status": "active", "monitoringType": "combined", "checkInterval": 1, "expectedState": "up", "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:00:00.000Z" } ``` Every website response carries `expectedState`: `up` or `down` for `heartbeat` monitors, always `up` for every other type. ## Common errors - `400 Website public ID (UUID) required` when `:websitePublicId` is missing/invalid - `401 Unauthorized` when you are not logged in - `404 Not Found` when the website does not exist **or belongs to another customer or organization** (the two cases are indistinguishable on purpose) ### Get Website Details URL: https://docs.uptimeify.io/api/websites/get-website-details Description: Returns the website detail page data in one call (mega endpoint). This includes monitoring stats, alert history, incident history, monitoring chart data, and maintenance windows. Summary: `GET /api/websites/:websitePublicId/details` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/websites/9a3d4d4d-7a4b-4f37-a9df-2a6f6d9d7a10/details?range=day" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Query Parameters - `range` (optional): `day` | `week` | `month` | `year` (default: `day`) - `date` (optional): reference date for calendar views - `startDate` / `endDate` (optional): custom date window for zoomed views - `granularity` (optional): e.g. `minute` for non-aggregated data (when supported) ## Response ```json { "website": { "id": 101, "name": "Main Marketing Site", "url": "https://deinkunde.com", "status": "active", "monitoringType": "combined", "customerId": 1 }, "uptimeStats": { "day": "100.00", "month": "99.95", "year": "99.90", "dayAvgResponse": 125, "monthAvgResponse": 118, "yearAvgResponse": 120, "blockedRatio": { "day": 0, "week": 0, "month": 0.02, "year": 0 } }, "monitoringData": { "responseTimeData": [], "statusData": [], "uptimePercentage": "99.95", "checkSuccessRatePercentage": "99.80", "totalChecks": 100, "successfulChecks": 99 }, "incidents": { "history": [], "total": 0, "ongoing": 0, "totalDowntime": "0m" }, "alerts": { "history": [], "total": 0, "notificationContext": null }, "maintenance": { "inMaintenance": false, "activeWindows": [], "allWindows": [] } } ``` ## Response Fields - `uptimeStats.day|week|month|year`: uptime percentage as a string with two decimals, or `null` when nothing was measurable in that period. The same holds for `monitoringData.uptimePercentage`. - `uptimeStats.blockedRatio`: per period, the share 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. - `uptimeStatsMeta.day|month|year`: `downtimeMinutes` and `incidents` for the period, plus `checksTotal` and `checksFailed`. For `day` these count check cycles (one per minute, failed when as many locations as the alert threshold failed together) over the last 24 hours. For `month` (the last 30 days) and `year` (since 1 January, UTC) they count single location checks of every check type, read from the 15-minute and daily aggregates, because the per-minute cycles are only kept for 7 days. Do not compare the day figure with the month or year figure directly. - `uptimeStats.dayAvgResponse|weekAvgResponse|monthAvgResponse|yearAvgResponse` and the matching `…AvgPageSize` fields: averages over the same windows as the uptime, the last 24 hours, 7 days and 30 days and the year since 1 January (UTC). `monthAvgPageSize` and `yearAvgPageSize` are `null`, because page size is kept for 7 days only. ## Common errors - `400 Invalid website public ID (UUID)` when `:websitePublicId` is invalid - `401 Unauthorized` when you are not logged in - `404 Not Found` when the website does not exist **or belongs to another customer or organization** (the two cases are indistinguishable on purpose) - `500 Failed to fetch website details` on server errors ## 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. ### List Websites URL: https://docs.uptimeify.io/api/websites/list-websites Description: Lists websites within an organization (paginated). Results are scoped by your session/permissions. Summary: `GET /api/websites` ## Query Parameters - `organizationId` (optional): Defaults to your session organization. - `customerId` (optional): Filter websites by customer. - `search` (optional): Search by website/customer fields. - `monitoringType` (optional): `combined` | `http_status` | `ssl_check` | `playwright` | `heartbeat` | `dns` - `excludeMonitoringType` (optional): same values as `monitoringType` - `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/websites?organizationId=1&page=1&perPage=50" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": 101, "publicId": "11111111-1111-4111-8111-111111111111", "customerId": 1, "customerPublicId": "22222222-2222-4222-8222-222222222222", "customerName": "Acme Corp", "name": "Main Marketing Site", "url": "https://deinkunde.com", "status": "active", "monitoringType": "combined", "checkInterval": 1, "createdAt": "2026-02-26T12:00:00.000Z" } ], "total": 1, "page": 1, "perPage": 50 } ``` Each item contains flat `customerName` and `customerPublicId` fields, not a full embedded `customer` object. ## Response Fields Unless you request the list with `skipMetrics=true`, each item also carries inline metrics: - `uptimeDay`, `uptimeMonth`, `uptimeYear`: uptime percentage as a string with two decimals, or `null` when nothing was measurable in that 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 a period that consists only of it has no percentage at all. - `avgResponseDay`, `avgResponseMonth`, `avgResponseYear`: average response time in milliseconds, `null` without measurements. ## Common errors - `400 Invalid customerId` when `customerId` is invalid - `400 Invalid monitoringType` when `monitoringType` is not supported - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization ### Rotate Heartbeat Token URL: https://docs.uptimeify.io/api/websites/rotate-heartbeat-token Description: Generates a new heartbeat token; the old one stops working immediately. Summary: `POST /api/websites/:websitePublicId/heartbeat-token/rotate` Generates a new heartbeat token for a heartbeat monitor. The old token stops working **immediately**: pings to the old ping URL are answered with `404` `heartbeatTokenNotFound`. There is no grace period, because a token is usually rotated after it leaked. Update your cron job or script with the new ping URL right away; the monitor itself, its history and its heartbeat state stay unchanged. ## Authentication Requires a valid session with write access to the monitor (organization editor or higher; customer-scoped logins only for their own self-service monitors). - Header: `Authorization: Bearer ` ## Parameters - `websitePublicId` (Path, required): public UUID (or numeric id) of the heartbeat monitor. No request body. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST \ "$BASE_URL/api/websites/6bfec6f6-245a-47ce-843b-157d97d56f88/heartbeat-token/rotate" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "id": 123, "publicId": "6bfec6f6-245a-47ce-843b-157d97d56f88", "heartbeatToken": "0f8e1c2a-6b4d-4e8a-9f3b-2d7c5a1e9b40" } ``` The new ping URL is `https://uptimeify.io/ping/` (or your custom domain). The audit log records the rotation without the token value. ## Common Errors - `400` `heartbeatMonitorRequired` if the monitor is not a heartbeat monitor - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have write access to the monitor - `404` `websiteNotFound` if the monitor does not exist or belongs to another organization ### Trigger Website Check URL: https://docs.uptimeify.io/api/websites/trigger-check Description: Triggers an immediate check of a website across eligible monitoring locations. Summary: `POST /api/websites/:websitePublicId/trigger-check` ## Authentication Requires a valid session with write access to the website. - Header: `Authorization: Bearer ` ## Parameters - `websitePublicId` (Path, required): Website public UUID. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST \ "$BASE_URL/api/websites/6bfec6f6-245a-47ce-843b-157d97d56f88/trigger-check" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "success": true, "message": "Check triggered successfully", "websiteId": 123 } ``` The check is enqueued for the website's active monitoring locations; results land in the check history a few seconds later. ## 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 write access to the website - `429 Check recently triggered` (`data.retryAfterMs`) when the same website was triggered within the last 10 seconds; the same cooldown every monitor family has - `503 No active monitoring locations available` ### Update Website URL: https://docs.uptimeify.io/api/websites/update-website Description: Updates a website. Supports both partial updates (only sent fields are changed) and full updates (all required fields must be present). Summary: `PATCH /api/websites/:websitePublicId` A request is treated as a **full update** when `customerId`, `name`, and `url` are all present in the body. Otherwise, it is treated as a partial update. ## Example (cURL): Partial update ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/websites/9a3d4d4d-7a4b-4f37-a9df-2a6f6d9d7a10" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "name": "Updated Website Name", "checkInterval": 5, "timeoutSeconds": 10 }' ``` ## Example (cURL): Full update with HTTP configuration ```bash curl -X PATCH "$BASE_URL/api/websites/9a3d4d4d-7a4b-4f37-a9df-2a6f6d9d7a10" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "customerId": 5, "name": "API Endpoint Monitor", "url": "https://api.deinkunde.com/health", "httpMethod": "POST", "customHeaders": { "X-API-Key": "abc123", "Content-Type": "application/json" }, "requestBody": "{\"check\": true}", "followRedirects": false, "cookieHandling": "jar", "mtlsEnabled": true, "mtlsClientCert": "", "mtlsClientKey": "" }' ``` ## Request Body For a **full update**, `customerId`, `name` and `url` are required; every other field is optional. A **partial update** applies these fields: `name`, `url`, `status`, `managementType`, `checkInterval`, `timeoutSeconds`, `expectedStatusCodes`, `searchTerm`, `checkExpectedResponseEnabled`, `expectedResponseMatchType`, `expectedResponseValue`, `expectedResponseJsonPath`, `heartbeatGracePeriodMinutes`, `expectedState`, `connectHost`, `connectPort`, `connectTlsInsecure`, the six check fields, `checkDomainExpiryEnabled`, `sslNoticeDays`, `sslErrorDays`, `domainExpiryNoticeDays`, `domainExpiryErrorDays`, `minPageSize` and `maxPageSize`. Everything else in the tables below (`monitoringType`, `allowedCheckCountryCodes`, `customFields`, the authentication, HTTP request, mTLS and Playwright fields, and `dnsConfig`) is applied by a full update only: sent on its own it is ignored, without an error. Send `customerId`, `name` and `url` alongside it, or use the dedicated endpoints where they exist. ### Core fields | Field | Type | Description | |-------|------|-------------| | `customerId` | number\|string | Customer public ID (preferred) or legacy numeric ID | | `name` | string | Display name (1-255 chars) | | `url` | string | URL to monitor (max 2048 chars). HTTP monitors need a full URL including protocol; DNS monitors take a bare hostname (no protocol, no path). | | `monitoringType` | string | `combined`, `http_status`, `ssl_check`, `playwright`, `heartbeat`, `dns` | | `status` | string | `active`, `inactive`, `maintenance` (`paused` → `inactive`) | | `checkInterval` | number | Check interval in minutes. 1-1440 (24 hours) for actively scheduled monitors, 1-43200 (30 days) for `heartbeat` monitors. The ceiling follows the monitor's type, taking `monitoringType` from the request when sent and the stored type otherwise. | | `timeoutSeconds` | number | Request timeout in seconds (1-60) | | `expectedStatusCodes` | string | Comma-separated expected HTTP status codes | | `allowedCheckCountryCodes` | string[]\|null | Array of 2-letter country codes, or null to reset to org default | | `searchTerm` | string\|null | Keyword to search for (null clears it) | | `customFields` | object\|null | Custom field values | | `managementType` | string | Ownership class: `managed` or `self_service`: see [Managed vs. Self-Service](/monitoring/managed-vs-self-service). Changing the class is organization-admin-only; flipping to `self_service` requires `allowSelfService` and free quota. | ### Authentication | Field | Type | Description | |-------|------|-------------| | `authMode` | string | `none`, `authorization_header`, `basic`. Setting to `none` clears auth credentials. | | `authorizationHeader` | string\|null | Required when `authMode` is `author… ### Whitelabel & Branding URL: https://docs.uptimeify.io/api/whitelabel Description: Customize your organization's product name, theme colors, logos, favicons, and custom domains. All whitelabel endpoints require admin or global admin role. Summary: ## Authentication All whitelabel endpoints require session authentication (not API tokens): ```bash BASE_URL="https://uptimeify.io" ``` ## Endpoints ### Branding - [Get Branding](/api/whitelabel/get-branding) - [Update Branding](/api/whitelabel/update-branding) - [Upload Branding Asset](/api/whitelabel/upload-branding) - [Delete Branding Asset](/api/whitelabel/delete-branding-asset) ### Domains - [List Domains](/api/whitelabel/list-domains) - [Get Domain](/api/whitelabel/get-domain) - [Domain Diagnostics](/api/whitelabel/get-domain-diagnostics) - [Add Domain](/api/whitelabel/add-domain) - [Verify Domain](/api/whitelabel/verify-domain) - [Activate Domain](/api/whitelabel/activate-domain) - [Delete Domain](/api/whitelabel/delete-domain) ### Activate Domain URL: https://docs.uptimeify.io/api/whitelabel/activate-domain Description: Activates a verified custom domain. Optionally sets it as the primary domain. Admin-only. Summary: `POST /api/organization/whitelabel/domains/activate` ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `domainId` | number | Yes | - | The verified domain ID to activate | | `makePrimary` | boolean | No | auto | Set this domain as primary. Auto-set to `true` if no primary exists. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/organization/whitelabel/domains/activate" \ -H "Cookie: $SESSION_COOKIE" \ -H "Content-Type: application/json" \ -d '{ "domainId": 2, "makePrimary": true }' ``` ## Response ```json { "activated": true, "domain": { "id": 2, "hostname": "app.deinkunde.com", "status": "active", "role": "app", "isPrimary": true, "verificationToken": "xyz789-abc456", "verifiedAt": "2026-04-15T12:30:00.000Z", "lastVerificationError": null, "lastVerificationErrorAt": null, "createdAt": "2026-04-15T12:00:00.000Z", "updatedAt": "2026-04-15T13:00:00.000Z" } } ``` ## Common errors - `400 Domain must be verified before activation` - `404 Domain not found` - `409 Conflict` (`domainAlreadyClaimed`) when another organization holds this hostname as verified or active meanwhile. The owner is not disclosed. ### Add Domain URL: https://docs.uptimeify.io/api/whitelabel/add-domain Description: Adds a custom domain for whitelabeling. Creates a pending DNS verification record. The first domain is automatically set as primary. Requires admin role. Summary: `POST /api/organization/whitelabel/domains` ## Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `hostname` | string | Yes | Custom domain hostname (3-253 chars). No wildcards. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/organization/whitelabel/domains" \ -H "Cookie: $SESSION_COOKIE" \ -H "Content-Type: application/json" \ -d '{ "hostname": "app.deinkunde.com" }' ``` ## Response ```json { "domain": { "id": 2, "hostname": "app.deinkunde.com", "status": "pending", "role": "app", "isPrimary": false, "verificationToken": "xyz789-abc456", "verifiedAt": null, "lastVerificationError": null, "lastVerificationErrorAt": null, "createdAt": "2026-04-15T12:00:00.000Z", "updatedAt": "2026-04-15T12:00:00.000Z" }, "dns": { "txtName": "_verify-status.app.deinkunde.com", "txtValue": "xyz789-abc456" } } ``` Add a DNS TXT record with the `txtName` and `txtValue`, then call [Verify Domain](/api/whitelabel/verify-domain). ## Common errors - `400 Invalid hostname` when hostname format is wrong - `400 This hostname is reserved` (`hostnameReserved`) when the hostname is one of the platform's own hosts or anything under `uptimeify.io` - `400 Wildcard domains are not supported` - `409 Hostname already exists` (`hostnameAlreadyExists`) when your organization already has a row for this hostname A hostname is only claimed once it is **verified** or **active**. Another organization's unverified request does not block yours, and yours does not block theirs; the claim is decided at [Verify Domain](/api/whitelabel/verify-domain). A `pending` request that is never verified is removed after 7 days. ### Delete Branding Asset URL: https://docs.uptimeify.io/api/whitelabel/delete-branding-asset Description: Removes an uploaded logo or favicon. Requires admin role; works with API tokens. Summary: `DELETE /api/organization/whitelabel/branding/{kind}` `kind` is one of `logo`, `logoLight`, `logoDark`, `favicon`, `faviconLight`, `faviconDark`, the same values as for the upload. `logo` and `logoLight` both remove the light logo, `favicon` and `faviconLight` the light favicon. The stored file is deleted once no other branding slot refers to it. Without a logo or favicon the app shows the default one again. ## Example (cURL) ```bash curl -X DELETE "$BASE_URL/api/organization/whitelabel/branding/logoDark" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Response `204 No Content` without a body. Read the new state with `GET /api/organization/whitelabel/branding`. ## Common errors - `400 invalidBrandingAssetKind` when `kind` is not one of the six values - `403 Forbidden` when not an admin - `404 brandingAssetNotFound` when nothing is uploaded for this kind (also on a second DELETE) ### Delete Domain URL: https://docs.uptimeify.io/api/whitelabel/delete-domain Description: Deletes a custom domain. If the deleted domain was primary, the next available domain is promoted to primary. Admin-only. Summary: `DELETE /api/organization/whitelabel/domains/:id` ## Example (cURL) ```bash curl -X DELETE "$BASE_URL/api/organization/whitelabel/domains/2" \ -H "Cookie: $SESSION_COOKIE" ``` ## Response ```json { "success": true } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when not an admin - `404 Domain not found` ### Get Branding URL: https://docs.uptimeify.io/api/whitelabel/get-branding Description: Returns the organization's branding configuration, including product name, theme colors, and signed URLs for logos and favicons. Requires admin role. Summary: `GET /api/organization/whitelabel/branding` ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/organization/whitelabel/branding" \ -H "Cookie: $SESSION_COOKIE" \ -H "Accept: application/json" ``` ## Response ```json { "branding": { "productName": "Acme Monitor", "hideProductName": false, "logoObjectKey": "branding/org-1/logo/light/1710000000-logo.svg", "logoObjectKeyLight": "branding/org-1/logo/light/1710000000-logo.svg", "logoObjectKeyDark": "branding/org-1/logo/dark/1710000000-logo-dark.svg", "hideLogos": false, "faviconObjectKey": "branding/org-1/favicon/light/1710000000-favicon.ico", "faviconObjectKeyLight": "branding/org-1/favicon/light/1710000000-favicon.ico", "faviconObjectKeyDark": "branding/org-1/favicon/dark/1710000000-favicon-dark.ico", "themePrimary": "#43B1AE", "themeSecondary": null, "logoUrl": "https://s3.deinkunde.com/branding/org-1/logo/light/1710000000-logo.svg?...", "logoLightUrl": "https://s3.deinkunde.com/branding/org-1/logo/light/1710000000-logo.svg?...", "logoDarkUrl": "https://s3.deinkunde.com/branding/org-1/logo/dark/1710000000-logo-dark.svg?...", "faviconUrl": "https://s3.deinkunde.com/branding/org-1/favicon/light/1710000000-favicon.ico?...", "faviconLightUrl": "https://s3.deinkunde.com/branding/org-1/favicon/light/1710000000-favicon.ico?...", "faviconDarkUrl": "https://s3.deinkunde.com/branding/org-1/favicon/dark/1710000000-favicon-dark.ico?...", "updatedAt": "2026-03-01T10:00:00.000Z" } } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when not an admin ### Get Domain URL: https://docs.uptimeify.io/api/whitelabel/get-domain Description: Returns one custom app domain of your organization, in the same { domain, dns } shape as Add Domain. Requires the admin role. Summary: `GET /api/organization/whitelabel/domains/{id}` ## Access Organization admins only, as for [List Domains](/api/whitelabel/list-domains). Only domains with the role `app` are returned. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/organization/whitelabel/domains/3" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "domain": { "id": 3, "hostname": "monitoring.acme.example", "status": "active", "role": "app", "isPrimary": true, "verificationToken": "uptimeify-verify-def456", "verifiedAt": "2026-06-02T08:00:00.000Z", "lastVerificationError": null, "lastVerificationErrorAt": null, "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-02T08:00:00.000Z" }, "dns": { "txtName": "_verify-status.monitoring.acme.example", "txtValue": "uptimeify-verify-def456" } } ``` `domain.lastVerificationError` is the diagnosis of the last failed [verification](/api/whitelabel/verify-domain) (same fields as the `domainVerificationFailed` error data), with `domain.lastVerificationErrorAt`; both are `null` once a verification succeeded. For a live check of DNS and certificate use [Domain Diagnostics](/api/whitelabel/get-domain-diagnostics). ## Common errors - `400 Bad Request` (`invalidDomainId`) when the id is not a positive number - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you are not an organization admin - `404 Not Found` (`domainNotFound`) when the domain does not exist or belongs to another organization ### Domain Diagnostics URL: https://docs.uptimeify.io/api/whitelabel/get-domain-diagnostics Description: Live DNS and certificate check of one custom app domain: authoritative nameservers, TXT record seen, propagation, certificate state, last failed verification. Requires the admin role. Summary: `GET /api/organization/whitelabel/domains/{id}/diagnostics` Runs the checks live on every call and writes nothing. Use it when a domain does not verify or does not serve HTTPS. ## Access Organization admins only, as for [Get Domain](/api/whitelabel/get-domain). ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/organization/whitelabel/domains/12/diagnostics" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "domainId": 12, "hostname": "status.acme.example", "status": "active", "checkedAt": "2026-10-29T09:30:00.000Z", "verification": { "recordFound": true, "recordName": "_verify-status.status.acme.example", "expected": "uptimeify-verify-abc123", "lookup": "records", "observed": ["uptimeify-verify-abc123"], "nameservers": { "zone": "acme.example", "hosts": ["ns1.dns-provider.example", "ns2.dns-provider.example"] }, "authoritative": { "nameserver": "ns1.dns-provider.example", "lookup": "records", "observed": ["uptimeify-verify-abc123"] }, "propagation": "propagated" }, "certificate": { "state": "valid", "errorCode": null, "errorMessage": null, "issuer": "Let's Encrypt", "validFrom": "2026-10-01T00:00:00.000Z", "validTo": "2026-12-30T00:00:00.000Z", "daysUntilExpiry": 62 }, "lastVerificationError": null, "lastVerificationErrorAt": null } ``` | Field | Description | |-------|-------------| | `verification` | The live TXT check, `null` when the domain has no verification token. Same fields as the `domainVerificationFailed` error data of the verify endpoint, plus `recordFound` (`true`: the token is published, verify would succeed). | | `verification.nameservers` | The zone the hostname is delegated in and its authoritative nameservers; `null` if that could not be determined. | | `verification.authoritative` | What one of those nameservers answered when asked directly, bypassing every cache; `null` if none could be asked. Only public nameserver addresses are queried. | | `verification.propagation` | `propagated` (our resolver sees the token), `propagating` (your nameserver has it, our resolver not yet; retry after the TTL), `not_published` (not even your nameserver has it), `unknown` (no nameserver could be asked). | | `certificate.state` | What a browser gets on `https://`: `valid`, `invalid` (a certificate is served but fails verification, reason in `errorCode`), `handshake_failed` (no TLS handshake: the certificate may still be issuing, or the CNAME does not point to us yet), `unreachable` (`errorCode` `not_resolved` or `private_address`), `not_active` (the domain is not activated yet, no certificate is issued before that, nothing was probed). | | `certificate.errorCode` | `expired`, `not_yet_valid`, `hostname_mismatch`, `untrusted`, `not_resolved`, `private_address` or `null`. | | `lastVerificationError`, `lastVerificationErrorAt` | The last failed verification as stored on the domain, `null` after a successful one. | ## Common errors - `400 Bad Request` (`invalidDomainId`) when the id is not a positive number - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you are not an organization admin - `404 Not Found` (`domainNotFound`) when the domain does not exist or belongs to another organization ### List Domains URL: https://docs.uptimeify.io/api/whitelabel/list-domains Description: Returns all custom app domains for the organization. Only domains with role app are returned. Requires admin role. Summary: `GET /api/organization/whitelabel/domains` ## 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/whitelabel/domains?envelope=items" \ -H "Cookie: $SESSION_COOKIE" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": 1, "hostname": "app.deinkunde.com", "status": "active", "role": "app", "isPrimary": true, "verificationToken": "abc123-def456", "verifiedAt": "2026-01-15T10:00:00.000Z", "lastVerificationError": null, "lastVerificationErrorAt": null, "createdAt": "2026-01-14T08:00:00.000Z", "updatedAt": "2026-01-15T10: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 (`{ "domains": [...] }`), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when not an admin ### Update Branding URL: https://docs.uptimeify.io/api/whitelabel/update-branding Description: Updates the organization's branding configuration. All fields are optional: only sent fields are updated. Setting productName or theme colors to null clears them. Requires admin role. Summary: `PATCH /api/organization/whitelabel/branding` Theme colors accept CSS custom property tokens (e.g. `--color-red-500`) or hex colors (e.g. `#43B1AE`). Invalid values are rejected. ## Request Body (all optional) | Field | Type | Description | |-------|------|-------------| | `productName` | string\|null | Product display name (1-80 chars). `null` clears it. | | `hideProductName` | boolean | Hide the product name in the UI | | `hideLogos` | boolean | Hide all logos in the UI | | `themePrimary` | string\|null | Primary theme color (hex or CSS variable). `null` clears it. | | `themeSecondary` | string\|null | Secondary (neutral) theme color (hex or CSS variable), the same name the response uses. `null` clears it. | | `themeNeutral` | string\|null | Deprecated, use `themeSecondary`; removed on 2027-02-01. Still accepted; when both are sent, `themeSecondary` wins. | Fields you leave out keep their stored value (merge patch). Until 28.10.2026 `productName` had to be sent with every request; it is optional now. ## Example (cURL) ```bash curl -X PATCH "$BASE_URL/api/organization/whitelabel/branding" \ -H "Cookie: $SESSION_COOKIE" \ -H "Content-Type: application/json" \ -d '{ "productName": "Acme Monitor", "themePrimary": "#43B1AE", "hideProductName": false }' ``` ## Response ```json { "branding": { "productName": "Acme Monitor", "hideProductName": false, "hideLogos": false, "themePrimary": "#43B1AE", "themeSecondary": null, "updatedAt": "2026-04-15T12:00:00.000Z" } } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when not an admin ### Upload Branding Asset URL: https://docs.uptimeify.io/api/whitelabel/upload-branding Description: Uploads a logo or favicon as a base64 data URL. Assets are stored in S3 and the branding record is updated automatically. Requires admin role. Summary: `POST /api/organization/whitelabel/branding/upload` **Logo** types: `logo`, `logoLight`, `logoDark`: accepts PNG, JPEG, WebP, SVG (max 2 MB). **Favicon** types: `favicon`, `faviconLight`, `faviconDark`: accepts PNG, SVG, ICO (max 512 KB). Legacy `logo` is treated as `logoLight`, and `favicon` as `faviconLight`. ## Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `kind` | string | Yes | `logo`, `logoLight`, `logoDark`, `favicon`, `faviconLight`, `faviconDark` | | `fileName` | string | Yes | Original file name (1-200 chars) | | `dataUrl` | string | Yes | Base64 data URL (`data:*/*;base64,...`) | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/organization/whitelabel/branding/upload" \ -H "Cookie: $SESSION_COOKIE" \ -H "Content-Type: application/json" \ -d '{ "kind": "logoLight", "fileName": "logo.svg", "dataUrl": "data:image/svg+xml;base64,PHN2Zy..." }' ``` ## Response ```json { "success": true, "uploaded": { "kind": "logo", "objectKey": "branding/org-1/logo/light/1710000000-logo.svg", "contentType": "image/svg+xml", "bytes": 1234, "publicUrl": "https://s3.deinkunde.com/branding/org-1/logo/light/1710000000-logo.svg?..." }, "branding": { "productName": "Acme Monitor", "hideProductName": false, "logoUrl": "https://s3.deinkunde.com/...", "themePrimary": "#43B1AE", "updatedAt": "2026-04-15T12:00:00.000Z" } } ``` ## Common errors - `400 Invalid dataUrl` when the data URL format is wrong - `400 Unsupported contentType` when the content type is not allowed for the asset kind - `413 File too large` when exceeding size limits - `503 Whitelabel asset storage is not configured` when S3 is not set up ### Verify Domain URL: https://docs.uptimeify.io/api/whitelabel/verify-domain Description: Verifies DNS TXT records for a custom domain. Admin-only. Summary: `POST /api/organization/whitelabel/domains/verify` ## Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `domainId` | number | Yes | The domain ID to verify | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/organization/whitelabel/domains/verify" \ -H "Cookie: $SESSION_COOKIE" \ -H "Content-Type: application/json" \ -d '{ "domainId": 2 }' ``` ## Response (success) ```json { "verified": true, "status": "verified", "domain": { "id": 2, "hostname": "app.deinkunde.com", "status": "verified", "role": "app", "isPrimary": false, "verificationToken": "xyz789-abc456", "verifiedAt": "2026-04-15T12:30:00.000Z", "lastVerificationError": null, "lastVerificationErrorAt": null, "createdAt": "2026-04-15T12:00:00.000Z", "updatedAt": "2026-04-15T12:30:00.000Z" } } ``` ## Common errors - `400 domainVerificationFailed` when the TXT record was not found. The error data says what we saw, so you can fix the record without guessing: ```json { "statusCode": 400, "statusMessage": "TXT verification failed (token not found)", "data": { "code": "domainVerificationFailed", "recordName": "_verify-status.app.example.com", "expected": "xyz789-abc456", "lookup": "records", "observed": ["old-token-from-another-tool"], "nameservers": { "zone": "example.com", "hosts": ["ns1.dns-provider.example", "ns2.dns-provider.example"] }, "authoritative": { "nameserver": "ns1.dns-provider.example", "lookup": "records", "observed": ["a1b2c3d4e5f6"] }, "propagation": "propagating" } } ``` `lookup` is `records` (TXT values found, none matches; they are in `observed`, at most 10), `noRecords` (the name exists but has no TXT record), `nxdomain` (the name does not exist), `timeout` or `error` (resolver failure, retry later). `nameservers` is the zone the hostname is delegated in and its authoritative nameservers (`null` if that could not be determined). `authoritative` is what one of those nameservers answered when asked directly for `recordName`, bypassing every cache (`null` if none could be asked; only public addresses are queried). `propagation` reads both answers: `propagating` (your nameserver has the token, our resolver does not see it yet, retry after the TTL), `not_published` (not even your nameserver has it), `unknown` (no nameserver could be asked). The failure is also stored on the domain: every domain response carries it as `lastVerificationError` with `lastVerificationErrorAt` until the next successful verification clears both. - `400 Domain has no verification token` - `404 Domain not found` - `409 Conflict` (`domainAlreadyClaimed`) when another organization has already verified or activated this hostname. The owner is not disclosed. ## Examples ### Examples URL: https://docs.uptimeify.io/examples Description: Practical examples for common workflows with customers, websites, and monitors. Summary: This page has moved into the API documentation. Continue here: - [Examples (API)](/api/examples) - [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/examples/create-customer-and-all-monitors Description: Example automation: create one website and then create one monitor of each type. Summary: This page has moved into the API documentation. Continue here: - [Create a customer + all monitor types (API)](/api/examples/create-customer-and-all-monitors) ### Create a customer + multiple monitors URL: https://docs.uptimeify.io/examples/create-customer-and-multiple-monitors Description: Example: create a customer and set up multiple monitors (same type and mixed types). Summary: This page has moved into the API documentation. Continue here: - [Create a customer + multiple monitors (API)](/api/examples/create-customer-and-multiple-monitors) ### Create a customer + website URL: https://docs.uptimeify.io/examples/create-customer-and-website Description: End-to-end example: create a customer and then create the first website. Summary: This page has moved into the API documentation. Continue here: - [Create a customer + website (API)](/api/examples/create-customer-and-website) ### Delete a customer including all websites URL: https://docs.uptimeify.io/examples/delete-customer-and-all-websites Description: Safe deletion flow: remove websites first, then delete the customer. Summary: This page has moved into the API documentation. Continue here: - [Delete a customer including all websites (API)](/api/examples/delete-customer-and-all-websites) ## Incident Management ### Incident Management URL: https://docs.uptimeify.io/incident-management Description: How Incident Management works: alert sources, routing, teams, on-call schedules, escalation, notifications, status pages and reports, and how to set it up. Summary: Incident Management (IM) turns alerts into incidents and makes sure the right person is woken up. It works next to [Monitoring](/monitoring): Uptimeify's own checks are one alert source among others (Zabbix, Datadog, Grafana, Prometheus, Sentry, email, your own webhook or code). Everything below can also be done through the [Incident Management API](/api/incident-management). ## Who can use it Organization members with the role `admin`, `editor` or `responder`. Customer logins (`readonly`) have no access. Within a team, every member (team role `admin`, `member` or `stakeholder`) may work on that team's incidents; team admins may also change the team itself. Organization admins may do both for every team. ## Setting it up 1. **Activate** Incident Management for your organization (organization admin). In the dashboard: **Incidents**. API: [Activate](/api/incident-management/activate). 2. **Create a team** and add its members (**Incidents → Teams**). 3. **Create a schedule** for the team: who is on call when, and how the rotation moves on. 4. **Build the escalation chain** of the team: tier 1 is paged first; each tier has its schedules and decides when the incident moves on to the next tier. 5. **Connect an alert source** (**Incidents → Sources**): pick a preset, copy its ingest URL into your tool. The [setup guides](/api/incident-management/alert-sources) cover each tool. 6. **Set your own notifications** (**Incidents → Notifications**): how and after how long you are reached, and verify your phone number for SMS and voice calls. 7. **Send a test page** to check that paging reaches you. ## From alert to incident - An **alert** is one signal from a source. Alerts with the same deduplication key belong together, so a flapping check does not open ten incidents. - An **incident** groups alerts and is what people work on. It has a **severity** (`sev1` most severe to `sev4`) and a **status**: `triggered` (nobody has reacted yet), `acknowledged`, `investigating`, `identified`, `monitoring`, and finally `resolved` (or `merged` into another incident). - **Routing rules** decide which team a new incident goes to, for example by source or customer, and can override its severity. Without a matching rule, the source's default team takes it. - The **monitoring bridge** (organization settings) brings incidents from Uptimeify's own checks into Incident Management automatically. ## On-call and escalation - A **schedule** defines rotations: who is on shift and when the shift hands over. - An **override** replaces the schedule for a period: someone takes over a shift, or hands it off while unavailable. - The **escalation chain** pages tier 1 first. If nobody acknowledges within the tier's time, the next tier is paged. A tier can be paged again before moving on, and the whole chain can repeat. - On an incident you can **acknowledge** (stops escalation), **snooze** (pause escalation and reminders for up to 7 days), **escalate now** (page the next tier immediately), **add a responder**, **comment**, **change severity**, **merge** duplicates and **resolve**. ## How you are notified Each person decides for themselves how they are reached: - **Channels**: push (mobile app), SMS, voice call, email. SMS and voice need a verified phone number. - **Rules per urgency**: for example "push immediately, SMS after 5 minutes, call after 10 minutes". - **Severity filter**: for example no SMS or calls for `sev4`. - The **notification log** shows every notification that was sent, skipped or failed for you, and whether an SMS arrived or a call was answered. - **Alert calls** say "Uptimeify alert." first, read the incident three times and take 4 as the acknowledgement; a call that ends without the 4 (not answered, busy, or picked up by voicemail or call screening) is redialled once after one minute. Save the numbers we call and text from as a contact (button on the notifications page) and allow it through Do Not Disturb. Shared **channels** (webhook, Slack, email) bel… ## Incidents ### Incidents URL: https://docs.uptimeify.io/incidents Description: Incidents are created automatically when monitoring detects a problem with a website or service. They are the foundation for alerting, reporting, and the public Status Pages. Summary: ## Where to find incidents - **Incidents overview**: `/incidents` - **Per website / monitor**: most detail pages include an incident history tab ## Incident lifecycle Incidents have two primary states: - `open`: the issue is still ongoing - `resolved`: the service recovered and the incident was closed (automatically, once checks pass again) ## What an incident contains Depending on the check type, an incident can include: - **Type / severity**: for example `downtime`, `http_status`, `performance`, `ssl_warning`, `ssl_expiry`, `ssl_handshake` - **Start / resolved time** - **HTTP status code** (if applicable) - **Response time (ms)** (if applicable) - **Error message**: network errors, timeouts, parsing failures, etc. - **Last notified timestamp**: used for notification reminders **`ssl_handshake`**: the server aborted the TLS handshake (for example with an `internal_error` alert) and never established a secure connection, so the site is unreachable over HTTPS. ### How certificate problems are classified A certificate problem is only a warning while visitors can still reach the site. Once a browser *rejects* the certificate, the site is unreachable, and the incident is treated like any other outage: - **`downtime`** means the certificate is rejected right now: it has expired, it was revoked, or a real browser refused the page (for example `net::ERR_CERT_COMMON_NAME_INVALID` for a hostname the certificate is not valid for). Visitors see a full-page interstitial instead of your site, so this is an outage and alerts at critical severity. The error message on the incident still names the certificate cause. - **`ssl_expiry`**, the certificate is still valid but has reached the critical threshold before expiry. Nobody is blocked yet; this is a warning. - **`ssl_warning`**, a certificate problem we could not prove is blocking visitors. Also a warning. ## When your server rate-limits our checks **`rate_limited`**: your server answered our checks with `429 Too Many Requests` from at least three locations within 15 minutes, while a real browser still loaded the page. This is a notice, not an outage: - It does not count against your uptime and never appears on your public status page. There are no reminders. - While it lasts, we cannot measure the site. If the response carries a `Retry-After` header, we check from another location until it expires. - It resolves on its own after 15 minutes without a `429`. You get at most one notice per monitor every 6 hours. - You can switch it off per channel in the notification rules ("Server Rate-Limiting Checks (429)"). If real visitors are throttled as well, check your rate limit, WAF or bot protection, or allowlist our check IPs. ## Incident details (timeline & evidence) From the incidents list, open the **details modal** to see: - A **timeline** of confirmation → outage → recovery - The **evidence check** (the monitoring check that served as proof) - An optional **traceroute excerpt** - An optional **screenshot** (when available) This answers "what exactly happened?" without digging through raw logs. ## How incidents map to status page state If the customer has a public [status page](/status-pages), open incidents change the displayed service state: | Incident situation | Status page `state` | |--------------------|---------------------| | No open incidents | `operational` | | Only **SSL warning** incidents open | `warning` | | Any other open incident (downtime, http_status, performance, …) | `degraded` | | Active maintenance window, no open incidents | `maintenance` | The overall page banner reflects the most severe state across all services. See [Status Pages → How the public state is derived](/status-pages#how-the-public-state-is-derived). ## Inconclusive checks (browser verification timeouts) Some sites use bot protection / browser verification that can time out. In these cases Uptimeify may mark a check as **inconclusive** rather than treating it as full downtime. So you don't get misleading "… ## Integrations ### Integrations URL: https://docs.uptimeify.io/integrations Description: Uptimeify delivers alerts to the tools you already use, chat, on-call, issue trackers and more, plus firewall allowlisting and a full REST API. Summary: ## Notification channels Deliver alerts to where your team already works. Channels are configured per customer and attached to your notification rules. - Manage in the app under the customer's **Notifications** settings. - Automate with the [Notification Channels API](/api/notification-channels) (create, list, update, delete, and **test** a channel). Every channel below is supported out of the box. ### Direct | Channel | Delivers via | You provide | |---------|--------------|-------------| | **Email** | E-mail | Recipient address(es); falls back to the customer/org email | | **SMS** | Text message | Phone number(s); falls back to the customer/org phone | | **Webhook** | Your HTTP endpoint | Endpoint URL (optional custom headers and JSON body template) | The exact JSON a Webhook channel posts, its request headers and signature verification are documented in the [Webhook payload reference](/integrations/webhooks). ### Chat & collaboration | Channel | You provide | |---------|-------------| | **Slack** | Incoming webhook URL (optional username, icon, color) | | **Microsoft Teams** | Incoming webhook URL | | **Discord** | Incoming webhook URL (optional username, color) | | **Telegram** | Bot token + chat ID | | **Google Chat** | Incoming webhook URL | | **Mattermost** | Incoming webhook URL | | **Rocket.Chat** | Incoming webhook URL | | **Matrix** | Homeserver URL + room ID + access token | | **Lark / Feishu** | Incoming webhook URL | | **DingTalk** | Incoming webhook URL (access token in the URL) | | **WeCom** | Incoming webhook URL (key in the URL) | ### On-call & incident response | Channel | You provide | |---------|-------------| | **PagerDuty** | Events API v2 routing key | | **Opsgenie** | API key + region (EU/US), optional priority | | **ilert** | Integration key | | **Grafana OnCall** | Incoming webhook URL | | **Squadcast** | Incoming webhook URL (token in the URL) | | **incident.io** | Alert source URL + bearer token | | **All Quiet** | Inbound webhook URL (the URL is the secret) | ### Push & lightweight | Channel | You provide | |---------|-------------| | **Pushover** | User key + API token | | **ntfy** | Topic URL (optional access token) | | **Gotify** | Server URL + app token | ### Issue trackers & ITSM | Channel | You provide | |---------|-------------| | **Jira** | Base URL + email + project key + issue type + API token | | **GitHub** | Repository + token (PAT); optional Enterprise API base URL | | **GitLab** | Project ID + token; optional self-hosted base URL | | **Linear** | Team ID + API key | | **ServiceNow** | Instance URL + username + password | ## Escalation policies Define multi-step, time-based escalation so an unacknowledged alert moves to the next responder automatically. - Configure and test via the [Escalation API](/api/escalation). ## Firewall allowlisting If your site sits behind a firewall or WAF, allowlist our monitoring nodes so checks aren't blocked. - See [Firewall allowlisting](/integrations/firewall) for the dashboard and `GET /api/ips` endpoint. - The full node list is published at [/ips.txt](https://uptimeify.io/ips.txt). Whitelisting other providers? See [Monitoring IP whitelists](https://uptimeify.io/compare/uptimerobot/probe-ips). ## API & automation Everything above, and the rest of the platform, is scriptable. - Start with the [API Documentation](/api). - Generate a token under your account and authenticate with `Authorization: Bearer wsm_`. ### Firewall allowlisting (Monitoring node IPs) URL: https://docs.uptimeify.io/integrations/firewall Description: If your website is protected by a firewall or WAF, you may need to allowlist our monitoring nodes so we can reach your endpoint reliably. Summary: ## Dashboard (UI) You can view the current IP allowlist in the dashboard sidebar under “IP Addresses”. ## API (Automation) To fetch the current list programmatically, use the authenticated endpoint: - `GET /api/ips` ### Authentication Use an API token generated in the dashboard. ```bash BASE_URL="https://uptimeify.io" TOKEN="wsm_" curl -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/ips" ``` ### Response ```json { "ipv4": ["203.0.113.10"], "ipv6": ["2001:db8::10"], "locations": { "de-nbg": ["203.0.113.10"] }, "updated_at": "2026-01-01T00:00:00.000Z", "documentation": "https://uptimeify.io/docs/integrations/firewall" } ``` Notes: - The IP list can change over time. Don’t hard-code it permanently. - Prefer periodic syncing on your side (e.g. via a scheduled job). ## How to recognise our checks in your logs Besides the source IP, every check identifies itself in two ways. Either is enough to allowlist on, and both are stable, use them if you would rather not track a changing IP list. ### User-Agent Simple checks (HTTP, SSL, redirects) and screenshots send: ``` SiteMonitorBot/1.0 (+https://uptimeify.io) ``` Playwright monitors, keyword checks and expected-response checks send a normal Chrome User-Agent with that token **appended**: ``` Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36 SiteMonitorBot/1.0 (+https://uptimeify.io) ``` The browser prefix is deliberate. A Playwright monitor walks a real user journey, a login, a checkout, and many WAFs block a bare bot User-Agent outright. That would make us report an outage your visitors are not experiencing. So we keep the browser shape and add our name to it, rather than pretending to be nothing but a bot. If you match on User-Agent, match on the substring `SiteMonitorBot`, never on the full string, which carries a Chrome version that changes with every browser update. ### Request header Every check also sends: ``` X-Uptimeify-Monitor: 1 ``` This is the more reliable of the two: a CDN or reverse proxy can rewrite a User-Agent, and bot mitigation sometimes strips it. The header is a constant and never contains a monitor, customer or account identifier, nothing about your account is exposed to anyone reading your access log. ### Rate Checks arrive at the interval you configured, from each location you enabled. They do not crawl: a simple check is one request, a Playwright monitor is exactly the journey your script describes. ## Which bot is this, and how do I stop it Allowlisting is one direction. If you would rather block us, or you are looking at a client that is not a monitoring check at all, the full account is on [uptimeify.io/robot](https://uptimeify.io/robot): every automated client we operate, what each one requests and how often, the addresses it comes from, and ready-made rules for Cloudflare, nginx and Apache. Two clients besides `SiteMonitorBot` appear there. `UptimeifyStatusBot` reads the public status pages other companies publish about themselves. `UptimeifyToolsBot` fetches an address someone entered into one of our free tools or passed to our MCP server, once, with no schedule behind it. None of the three reads `robots.txt`. A monitoring check is ordered by the site owner, so a `Disallow` written by a third party would switch off a check somebody on your own team relies on. Blocking works at your CDN, WAF or web server. ### Single sign-on (OIDC and SAML) URL: https://docs.uptimeify.io/integrations/sso Description: Let your team sign in through your own identity provider (Keycloak, Microsoft Entra ID, ADFS, Google Workspace, Okta, Authentik) over OIDC or SAML 2.0 with automatic account creation and optional SSO-only enforcement. Summary: Uptimeify supports single sign-on over **OpenID Connect (OIDC)** or **SAML 2.0** per organization. Team members sign in through your identity provider (IdP); customer logins are not affected. Each organization uses **one** provider, OIDC or SAML. Steps 1 and 2 cover OIDC; SAML is described in [SAML 2.0](#saml-20). ## Requirements - You are an **admin** of your Uptimeify organization. - You can create an OIDC client (confidential, authorization code flow with PKCE) in your IdP. - You can add a DNS TXT record for the email domain your team uses. ## 1. Create the client in your IdP Create a confidential OIDC client and allow this redirect URI (shown in Uptimeify under **Settings → Security → Single sign-on** already before the first save, together with the scopes; `GET /api/organization/sso` returns both as `redirectUri` and `scopes`): ``` https://uptimeify.io/api/auth/sso/callback/org- ``` Scopes: `openid email profile`. The client secret stays with Uptimeify encrypted and is never shown again. ## 2. Set up SSO in Uptimeify Go to **Settings → Security → Single sign-on**, choose "OpenID Connect" and fill in: | Field | Meaning | |---|---| | Issuer URL | The issuer of your IdP, for example `https://login.microsoftonline.com/TENANT-ID/v2.0`. Uptimeify loads `/.well-known/openid-configuration` from it when you save. | | Client ID, client secret | From step 1. Leave the secret empty later to keep the stored one. | | Email domain | The domain of your team's addresses, for example `example.com`. One domain belongs to one organization only. | | Role for new users | `Read only`, `Editor`, `Responder` or `Admin`. People who sign in via SSO for the first time get an account in your organization with this role. | **Test connection** checks the issuer before (or after) you save, without storing anything: it loads the discovery document, compares the issuer and checks that the authorization, token, JWKS and (if present) userinfo endpoints use HTTPS, point to public addresses and answer. The JWKS must contain at least one key. The result lists each check; a failed check names the reason (for example `not reachable` or `HTTP 404`). The same check runs as `POST /api/organization/sso/test` (organization admins; body `{ "issuer": "https://..." }`, empty for the stored issuer). ## 3. Verify the domain Uptimeify shows a TXT record. Create it at your DNS provider, then click **Check**: ``` _uptimeify-sso.example.com TXT "uptimeify-sso=" ``` SSO only works once the domain is verified. Changing the domain, the issuer or the IdP requires verifying again. ## 4. Sign in On the login page, click **Sign in with SSO**, enter your work email and you are redirected to your IdP. Existing accounts of your organization with the same email are reused; addresses that belong to another Uptimeify organization are rejected. ## SSO only After the domain is verified and one SSO login succeeded, you can switch on **SSO only**. Team members can then no longer sign in with a password. Two exceptions: - **Admins** keep password and 2FA as emergency access, in case your IdP is down or misconfigured. - **Customer logins** (users with access to individual customers) are not affected. ## SAML 2.0 Instead of OIDC you can connect a SAML IdP. Under **Settings → Security → Single sign-on**, choose "SAML 2.0", paste or upload your IdP's **metadata XML**, set domain and default role, and save. Uptimeify then shows: | Field | Value | |---|---| | Entity ID (identifier) | `https://uptimeify.io/api/auth/sso/saml2/sp/metadata?providerId=org-` | | Reply URL (ACS) | `https://uptimeify.io/api/auth/sso/saml2/sp/acs/org-` | | SP metadata | the same URL as the entity ID, publicly reachable and downloadable as a file | You verify the domain with a TXT record as for OIDC (step 3). Rules: - Assertions must be **signed** (SHA-256 or stronger). SHA-1 is rejected. - **SP-initiated** sign-in only: sign-in always starts at Uptimeify ("Sign in with SSO"). Tiles in the… ### Webhook payload reference URL: https://docs.uptimeify.io/integrations/webhooks Description: The exact JSON Uptimeify POSTs to a generic webhook channel, the request headers it sends, and how to verify the HMAC signature. Summary: A **Webhook** notification channel delivers every alert, recovery, reminder and warning for a customer to an HTTP endpoint you control. This page documents the payload of the generic webhook channel: the JSON body, the request headers, and signature verification. Chat and on-call channels (Slack, Discord, Microsoft Teams, PagerDuty, Opsgenie, …) send a payload in that provider's own format instead. The body documented here is what a **Webhook** channel sends when no custom body template is configured. ## The request | Property | Value | |---|---| | Method | `POST` (configurable per channel) | | Content type | `application/json` | | Timeout | 30 seconds (configurable per channel) | An endpoint that repeatedly fails to accept a connection gets a shorter timeout per attempt. Delivery is not stopped by this; only the cost of a failing attempt goes down. ### Request headers | Header | Meaning | |---|---| | `User-Agent` | Identifies the Uptimeify monitoring fleet | | `X-Webhook-Timestamp` | Time the request was built, ISO 8601 (UTC) | | `X-Webhook-Attempt` | Attempt counter for this notification, starting at `1` | | `X-Webhook-Signature` | HMAC signature of the body, only when a secret is configured | | `X-Webhook-Signature-Algorithm` | `sha256`, sent alongside the signature | Custom headers configured on the channel are merged in and win over the defaults. ## Verifying the signature When you configure a secret on the channel, we sign the **exact bytes of the request body** with HMAC-SHA256 and send the result hex-encoded in `X-Webhook-Signature`. Verify against the raw body, before any JSON parsing and re-serialisation, otherwise whitespace differences will break the comparison. ```js function isValidSignature(rawBody, headerValue, secret) { const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex') const a = Buffer.from(expected, 'utf8') const b = Buffer.from(String(headerValue ?? ''), 'utf8') // Length check first: timingSafeEqual throws on differing lengths. return a.length === b.length && crypto.timingSafeEqual(a, b) } ``` ## Payload ```json { "type": "alert", "check_degraded": false, "incident_id": 8094, "message": "Website Acme Shop is DOWN", "expected_response_error": null, "ssl": null, "website": { "id": 10597, "name": "Acme Shop", "url": "https://shop.example.com", "custom_fields": {} }, "customer": { "id": 42, "name": "Acme GmbH", "email": "ops@example.com", "custom_fields": {} }, "incident": { "type": "http_status", "started_at": "19.08.2026, 17:32:04", "resolved_at": "N/A", "status": "open", "ssl": null, "error_details": { "check_degraded": false, "status_code": 503, "error_message": "Unexpected status code (503) (expected: 200)", "expected_response_error": null, "response_time_ms": 412, "blocking_response": { "status_code": 503, "vendor": "Cloudflare", "vendor_kind": "cdn", "headers": { "server": "cloudflare", "cf-ray": "a2daec8259183caa-CDG" }, "counter_probe": { "status": 200, "verdict": "request_signature" } } }, "locations": ["de-fra", "fi-hel", "pl-waw"], "screenshot": null, "screenshot_url": "https://…", "diagnostics": null } } ``` ### Top-level fields | Field | Type | Notes | |---|---|---| | `type` | string | `alert`, `recovery`, `reminder`, `warning`, `unstable` or `slow` | | `check_degraded` | boolean | `true` when the check could not reach a verdict, as opposed to a confirmed outage | | `incident_id` | number | Stable per incident, the same across alert, reminder and recovery | | `message` | string | One human-readable line, ready to post | | `expected_response_error` | string \| null | Convenience copy of `incident.error_details.expected_response_error` | | `ssl` | object \| null | Certificate details, set only for SSL incidents | | `website` | object | `id`, `name`, `url`, `custom_fields`, and `tags` (array of tag names, only present when the monitor has tags; a channel of the customer only sees the customer's own tags, never organization-wide ones) |… ## Maintenance ### Maintenance URL: https://docs.uptimeify.io/maintenance Description: Maintenance windows let you plan work (deployments, updates, migrations) without triggering noisy alerts. During an active window the affected target is treated as in maintenance. Alerts are suppressed and, if the customer has a status page, the service is shown as Maintenance instead of Degraded. Summary: ## Create a maintenance window Go to **Dashboard → Maintenance** and create a new window. Read-only users can create, edit, reactivate, and delete maintenance windows for the customers they are assigned to. Global support accounts cannot modify maintenance windows. | Setting | Description | |---------|-------------| | **Target** | One or more: a **website**, a **service monitor** (ICMP / SMTP / SSH / FTP / IMAP-POP), a **DNS monitor**, a set of **tags**, or the entire **customer**. See [Apply to multiple monitors or by tag](#apply-to-multiple-monitors-or-by-tag). | | **Name** | A friendly label, e.g. "Weekly updates". | | **Description** | Optional notes shown in history. | | **Start / End** | The window's time range. Times are interpreted in your timezone. | | **Active** | Toggle to enable/disable the window without deleting it. | ## Apply to multiple monitors or by tag A single maintenance window can cover many monitors at once: **Multi-monitor select in the form** In the maintenance window form, open the **Target** selector and pick any combination of websites and service monitors. All selected monitors are added to the window; they must all belong to the same customer. **Bulk "Set maintenance" from monitor lists** On any monitor list page (e.g. *Dashboard → Web*, *Dashboard → Server*) you can select multiple rows using the checkboxes, then choose **Set maintenance** from the bulk-action toolbar. This creates a single maintenance window covering all selected monitors at once, pre-populating the form with those monitors as targets. **Dynamic by-tag windows** Instead of (or in addition to) selecting individual monitors, you can select one or more **tags**. A tag-based window covers every monitor that currently carries the tag, and it stays current automatically: - A monitor **tagged after** the window is created is automatically covered; no update needed. - **Removing a tag** from a monitor drops it from coverage immediately. **Org-wide scope:** When you select tags with *no* explicit monitors and no customer context, the window is **org-wide**. It covers all monitors across the entire organization that carry those tags, regardless of which customer they belong to. Creating or editing an org-wide tag window requires **admin or editor** role; readonly users will receive a permission error. Tag coverage is evaluated live by the monitoring worker at the moment each check result arrives, so there is no lag between tagging a monitor and it being protected by the window. ## One-time vs recurring A window is either **one-time** (default) or **recurring**. Recurring windows carry a recurrence pattern: | Field | Meaning | |-------|---------| | `frequency` | `daily`, `weekly`, or `monthly` | | `interval` | Repeat every *N* days/weeks/months (e.g. `2` = every other week) | | `daysOfWeek` | For weekly: which days (`0` = Sunday … `6` = Saturday) | | `dayOfMonth` | For monthly: day of month (`1`-`31`) | | `endRecurrenceDate` | Optional date when the recurrence stops | The **Start / End** times define the window's length within each occurrence. ## Effect on status pages If the target's customer has a status page: - A target with an **active maintenance window** (and no open incidents) is shown as **Maintenance**. - Maintenance windows can also appear in **Recent History** (controlled by the status page's *Show recent maintenance* toggle, see [Status Pages](/status-pages#recent-history)). Maintenance does not override real outages: if there is an **open incident** during a maintenance window, the service is shown as **Degraded**, not Maintenance. See [Incidents](/incidents). ## Troubleshooting ### Window does not show as "active" - Verify **Active** is enabled. - Confirm the current time is between **Start** and **End**. - Check the start/end times are correct for your timezone. - For recurring windows, confirm today matches the recurrence pattern (`frequency`, `daysOfWeek`/`d… ## Monitoring ### Monitoring URL: https://docs.uptimeify.io/monitoring Description: Monitor the availability and performance of your websites and services. Summary: In this section you will find information about all monitor types and how to configure them. **Website & HTTP:** Uptime, Keyword, Response Time, Page Size, HTTPS Redirect, SSL **Network & Services:** ICMP, SMTP, IMAP/POP, SSH, TCP Port, FTP **DNS & Domain:** DNS, DNSBL, Domain Expiry **Advanced:** Heartbeat (Cron), Playwright (Synthetic Browser) For a full categorized overview see [Monitoring Types](/monitoring/monitoring-types). ## Getting started - Create your first monitor: [Set up an Uptime monitor](/monitoring/monitoring-types/uptime) - Overview of all available monitor types: [Monitoring Types](/monitoring/monitoring-types) ### Incident Management URL: https://docs.uptimeify.io/monitoring/incident-management Description: Incident Management (IM) is Uptimeify's on-call and incident-response layer: teams, on-call schedules, escalation policies, and alert ingestion from your own tools, separate from customer-facing Monitoring. Summary: Incident Management (IM) is a separate domain from Monitoring: a two-level alert/incident model built for **your own** on-call response, not for paging your clients. Where Monitoring watches your clients' websites and services and tells *them* (or you, on their behalf) when something is down, IM is the tool your own team uses to make sure the right person on your side gets woken up, whether the trigger is a monitoring outage, a webhook from Datadog or Grafana, or an email forwarded from a vendor. Incident Management has no customer-facing surface. Customer (`readonly`-role) logins never see it, in any phase, it is an internal tool for your organization's admins, editors, and responders. ## The model The top-level ownership unit, every schedule, policy, and incident belongs to exactly one team. On-call rotations: who covers a team, and when, including one-off overrides. Escalation policies: the ordered tiers that decide who gets paged, how, and when to escalate further. The sev1-sev4 scale that drives urgency, paging speed, and which rule chain fires. How SMS and voice paging draw on your existing SMS quota, and what happens when it runs out. How long alert payloads, resolved alerts, and outbound-delivery records are kept. ## Two-level alert/incident model An inbound signal (a webhook payload, a forwarded email, an API call, or a bridged monitoring outage) becomes an **alert** (`im_alert`). Alerts are deduplicated and grouped into an **incident** (`im_incident`), the object your team actually responds to: acknowledges, works, and resolves. Multiple alerts (a flapping check re-firing every minute) collapse into one incident, so your on-call engineer sees one page, not twenty. ## Getting started Incident Management must be activated per organization before any of its endpoints or pages work, an organization admin turns it on from **Dashboard → Incidents**. Once active, see the [Incident Management API](/api/incident-management) to ingest alerts and manage incidents programmatically, or the concept pages above to understand the on-call model itself. ### Policies URL: https://docs.uptimeify.io/monitoring/incident-management/policies Description: An escalation policy is the ordered set of tiers that decides who gets paged when an incident opens, how many times, and when to move to the next tier. Summary: An **escalation policy** belongs to exactly one [team](/monitoring/incident-management/teams) and decides what happens when one of that team's incidents opens: who gets paged, in what order, and when the engine gives up waiting and escalates further. ## Tiers A policy is an ordered list of **tiers** (`tierOrder`). Tier 1 fires after its own `delayMinutes` from the incident opening (`0` means immediately); if nobody acknowledges in time, the engine advances to tier 2, then tier 3, and so on. Each tier has: | Field | Meaning | |---|---| | `delayMinutes` | How long to wait, from the previous tier firing, before this tier fires. | | `targetType` | What this tier pages: `schedule` (whoever is currently on call for a given [schedule](/monitoring/incident-management/schedules)), `user` (a specific person), `team` (every member of a team), or `channel` (a notification channel, e.g. a Slack webhook). | | `repeatCount` / `repeatIntervalMinutes` | How many times, and how often, this tier re-pages its target before escalating onward, a repeat is a second (or third) attempt at the *same* tier, not a new one. | | `conditions` | An optional time-window restriction (recurring, wall-clock, IANA-zone-aware), a tier can be scoped to fire only during specific hours or weekdays, evaluated at the moment it would fire. `null` means the tier always fires. | ## Defaults A team can mark one policy `isDefault: true`. An incident created without an explicit policy, whether ingested from an alert source or created manually, resolves to the team's default policy. A team with no default policy configured pages nobody until one is set or a policy is chosen explicitly per incident. ## Acknowledgment timeout and reminders Two policy-level settings shape what happens after paging starts: - **`ackTimeoutMinutes`**, if set, an incident that was acknowledged but sees no further progress for this long resumes escalating from its current tier, rather than staying quiet indefinitely because someone tapped "acknowledge" and then walked away. - **`reminderIntervalMinutes`**, if set, an unresolved incident gets a recurring reminder notification at this interval, independent of the tier chain, so a long-running incident doesn't fade from view. Both are `null` (off) unless configured. ## Quota-aware paging SMS and voice tiers are subject to the organization's shared [SMS/voice quota](/monitoring/incident-management/quota-and-overage). When that quota is exhausted, a paid tier is skipped in favor of the next tier immediately rather than waiting out its delay, and free channels (push, email) keep notifying regardless. ### Quota & Overage URL: https://docs.uptimeify.io/monitoring/incident-management/quota-and-overage Description: SMS and voice paging in Incident Management draw on the same monthly quota as your customer-facing SMS alerts. Here's exactly what happens when it runs out. Summary: Incident Management doesn't have a separate telco quota. SMS and voice calls sent by IM (acknowledgment pages, escalation notifications) draw on **the same monthly SMS quota** your organization already has for customer-facing Monitoring alerts, one pool, one price per unit. A voice call costs exactly what an SMS costs and counts as one unit against the same allowance; see [pricing](https://uptimeify.io/pricing) for the included allowance per plan and the per-unit overage rate. ## What happens at the included limit As long as your organization is under its included monthly allowance, every SMS or voice send goes out normally, no distinction, no extra step. Once you're at or over the included allowance, what happens next depends on a single organization-level setting: **overage**. - **Overage off (the default)**, a paid send beyond the allowance is blocked. It is not silently dropped: the engine treats it as "no telco spend available right now" and falls back, as described below. You are never billed automatically for going over. - **Overage on** (opted in from your Incident Management settings), a send beyond the allowance goes out and is billed per unit, up to an optional monthly safety cap (a hard ceiling on overage spend) if you've set one. Once that cap would be exceeded, sends block again exactly as if overage were off. ## What happens when a send is blocked A blocked SMS/voice send never means the incident goes unpaged. Three things happen at once: 1. **Free channels keep going.** Push and email notifications for that same rule chain are unaffected and continue to fire, quota only ever gates the paid (SMS/voice) channels. 2. **Escalation skips ahead immediately.** Rather than waiting out the blocked tier's delay, the engine promotes the next escalation tier right away, the point of escalating is to reach *someone*, and a paid channel that can't send is a reason to try the next tier sooner, not later. 3. **One admin alert per organization per month.** The first time a send is blocked in a given calendar month, your organization's admins get an email explaining that the quota is exhausted, which incident triggered it, and how to fix it (enable overage, or raise the safety cap). This is deliberately throttled to one email per month, a single severe incident can otherwise exhaust quota (and would otherwise trigger this alert) many times in a few minutes. None of this requires any action from you to keep incidents visible: the worst case is that paging is slower (next tier instead of a retried SMS) and quieter (no SMS/voice at all until the next billing period, unless you opt in to overage), never invisible. ## Where to change it The overage opt-in (`overageEnabled`) is configured per organization from your Incident Management settings (**Dashboard → Incidents → Settings**) or via `PATCH /api/im/org-settings`. The optional monthly safety cap and per-unit overage price are part of your organization's existing SMS billing settings (**Dashboard → Billing**), the same cap that already applies to overage on customer-facing Monitoring SMS alerts, since both draw from the one pool. ### Retention URL: https://docs.uptimeify.io/monitoring/incident-management/retention Description: How long Incident Management keeps raw alert payloads, resolved alerts, outbound-delivery records and the incidents themselves, and what's kept indefinitely. Summary: Incident Management retains different pieces of an incident's history for different lengths of time. In short: the per-source daily aggregates are permanent, an incident keeps its full detail for a year and lives on as a daily aggregate for a second year, and the raw, potentially sensitive material behind it goes sooner than either. | Data | Retention | |---|---| | Alert raw payload (`im_alert.rawPayload`) | Nulled out 90 days after ingest | | Resolved alerts (the `im_alert` row itself) | Deleted 90 days after ingest | | Outbound-delivery records (integration forwarding history) | Deleted 90 days after they were sent | | Incidents, timeline events, assignments | Deleted 12 months after the incident was triggered | | Daily incident aggregate (volume, MTTA, MTTR per day, team and severity) | Deleted 24 months after the day it covers | | Per-source daily aggregates (alert/dedup/incident counts) | Retained indefinitely | ## Why the raw payload is nulled, not the alert `rawPayload` is the exact, unmodified body your source sent. A vendor's webhook can carry API keys or other secrets its operator put in it, so it isn't something to keep around forever just because the alert it produced still matters. `mappedFields` is the already-normalized, safe view the same payload maps onto (title, severity, host, etc.). It is separate from `rawPayload` and survives it; [Get Incident](/api/incident-management/get-incident) always returns `mappedFields`, never `rawPayload`, regardless of age. ## Why aggregates outlive the rows they're computed from A source's daily counts (shown on its Analytics tab) are retained indefinitely specifically so that deleting the underlying resolved-alert rows after 90 days doesn't erase your longer-term history of how a source or team is trending. You lose the individual alert once it ages out; you keep the shape of the trend. ## Why incidents keep 12 months of detail and 24 months of shape The same idea applied to incidents, one step at a time. For twelve months an incident is kept whole: its timeline, its assignments and the alerts it was built from, so a quarterly review, an annual report or an audit finds the real thing rather than a summary of it. That is twice the six-month window most incident tools open by default. Past twelve months the question people actually ask changes from "what happened in this incident" to "what did last year look like", and that question is answered by one row per day, team and severity carrying the volume, the acknowledgement latency and the resolution latency. Those rows are written nightly, before anything is deleted, and nothing is ever removed that they have not already recorded. They are kept for 24 months, so a year-over-year comparison always has both years in it. Two consequences worth knowing. An incident older than twelve months disappears from the incident list and from the API, including one that was somehow never resolved: the window is a clock, not a status. And percentiles cannot be recomputed from the aggregate, only totals and averages, so a report older than twelve months shows mean time to acknowledge and mean time to resolve rather than a p95. ### Schedules URL: https://docs.uptimeify.io/monitoring/incident-management/schedules Description: A schedule defines a team's on-call rotation (who covers it, and when) plus one-off overrides for swaps and time off. Summary: A **schedule** belongs to exactly one [team](/monitoring/incident-management/teams) and answers one question: who is on call, right now? An escalation policy tier can target a schedule directly, so "page whoever is on call" is a first-class routing target, not something you have to hand-maintain as a list of names. ## The rotation A schedule has exactly **one** rotation. Stacking coverage is done at the escalation tier (a tier can target several schedules) rather than inside a single schedule. A rotation period puts a **group** of members on call as *concurrent peers*: they are equals and do not cut each other. Which of them a given incident actually reaches is decided when the page happens, not here. How the group is formed: - **`none`**, no handover at all. Everyone in the schedule is on call for its whole active period, as one continuous shift. - **`auto`**, the member pool is chunked automatically into groups of the size you give. - **`explicit`**, you define the groups and their order yourself. How often it hands over: - **`daily`**, **`weekly`**, **`biweekly`**, **`monthly`**, at the time of day, weekday or day of month you set. - **`custom`**, every N `minutes`, `hours`, `days`, `weeks` or `months`. **The shortest shift is one minute**, and handover times are minute-precise at every cadence. Cadences below a day (`minutes`, `hours`) advance in absolute time rather than by wall clock, so a daylight-saving switch neither duplicates nor skips an hour's worth of handovers. Independently of the rotation, a schedule can carry **weekly windows** (recurring wall-clock windows such as "weekdays 09:00-18:00"), so business-hours-only coverage needs no separate schedule. Outside those windows the schedule simply has nobody on call. ## Materialization A background worker precomputes each schedule's rotation into concrete shift rows, up to 90 days ahead. This is deliberate: answering "who is on call right now" at escalation time is then an indexed timestamp lookup, not a live timezone/DST computation, the one place this must never disagree with what actually happened is exactly the moment someone is being paged. A fast cadence is precomputed less far ahead, because the number of rows is the horizon divided by the cadence, a one-minute rotation over 90 days would be 129,600 shifts per member. Such a schedule is kept roughly 41 hours ahead instead and topped up every hour. That is a limit on how far a *preview* reaches, not on coverage: paging always reads the shift that is current now. ## Overrides An **override** is a one-off "X covers for Y" window on top of the regular rotation, a holiday swap or sick-day cover, without editing the rotation itself. Overrides have no priority field: precedence between overlapping overrides is decided by creation order (the later-created one wins), and this is also the order the materializer reads them in. ## Timezone Every schedule has an IANA timezone. Handovers and restriction windows are evaluated in it, across daylight-saving transitions, a `09:00` handover means 09:00 in the schedule's own zone, not UTC. ## API See [Schedules](/api/incident-management/schedules), [Schedule Overrides](/api/incident-management/schedule-overrides), and [Who Is On Call](/api/incident-management/on-call). ### Severity URL: https://docs.uptimeify.io/monitoring/incident-management/severity Description: Incident Management uses a four-level sev1-sev4 scale that drives paging urgency, escalation speed, and which notification rule chain fires. Summary: Every Incident Management alert and incident carries a **severity**, one of: | Severity | Meaning | Urgency | |---|---|---| | `sev1` | Critical | High | | `sev2` | Error | High | | `sev3` | Warning | Low | | `sev4` | Info | Low | `sev1`/`sev2` page at **high urgency**, `sev3`/`sev4` at **low urgency**, urgency selects which of a user's notification rule chains fires (e.g. "push immediately, SMS after 5 minutes" for high urgency vs. a slower, quieter chain for low). Severity also drives which of your outbound integrations receive the incident, if you route by minimum severity. ## Where severity comes from An incident's severity is either: - **Derived from its alerts** (`severityManual: false`, the default), the incident's severity is the highest (most critical) severity across every alert grouped into it. A new `sev1` alert landing on an already-`sev3` incident bumps the whole incident to `sev1`; the incident never *quietly* de-escalates as its most severe alert resolves. - **Set by a human** (`severityManual: true`), a [manually created incident](/api/incident-management/create-incident) has no alert stream to derive severity from, so its creator sets it directly, and it stays sticky (the alert-derived `max()` logic never overrides it). An alert source's [payload mapping](/api/incident-management/alert-sources) can map a vendor's own severity/priority field onto `sev1`-`sev4` (with a configurable default for unmapped values), so an alert from Datadog, Grafana, or a custom webhook carries the right severity from the moment it's ingested. ## Routing rules and channels A routing rule or notification channel can specify a `minSeverity`, the incident must be at least this severe (this critical or worse) to trigger it. The default is `sev2`, so routine `sev3`/`sev4` alerts don't, by default, reach every configured integration. ### Teams URL: https://docs.uptimeify.io/monitoring/incident-management/teams Description: A team is Incident Management's top-level ownership unit, every schedule, escalation policy, and incident belongs to exactly one team. Summary: A **team** is the top-level ownership unit in Incident Management. Every [schedule](/monitoring/incident-management/schedules), every [escalation policy](/monitoring/incident-management/policies), and every incident belongs to exactly one team, there is no cross-team or org-wide incident, by design. A small organization might run everything through a single "Default Team"; a larger one splits by service, product, or on-call rotation. ## Membership and roles A user becomes a team member with an `im_team_member.imRole` of either: - **`member`**, can be scheduled, paged, and assigned to incidents owned by the team. - **`admin`** (team admin), additionally may edit the team, and create/edit/delete its schedules, escalation policies, alert sources, and routing rules. Team-admin is scoped to that one team, it does not grant org-wide write access. An organization-level `admin` role always has full write access to every team, without needing team membership at all. ## Write access Mutating a team or its membership requires one of: - the organization's own `admin` role, or - a global admin (cross-org support access), or - a user who is themselves a team admin **of that specific team**. The same bar applies to creating a schedule, escalation policy, alert source, or routing rule under a team: org-admin, or admin of that team. ## Analytics A team has an `analyticsEnabled` flag ("Enable analytics") that turns on response/resolution metric tracking (MTTA/MTTR) for that team. It defaults to off for a new team. ## API See [Teams](/api/incident-management/teams) for the public read endpoint. ### Managed vs. Self-Service Monitors URL: https://docs.uptimeify.io/monitoring/managed-vs-self-service Description: Every monitor has an ownership class that controls who may edit it and who receives its alerts. Summary: Every monitor, website, DNS, ICMP, SMTP, SSH, FTP, IMAP/POP, domain expiry, and DNSBL, carries an **ownership class** (`managementType`) with one of two values: - **`managed`** (default): the organization runs the monitor on the customer's behalf. It is **read-only in the customer portal**; customers request edits through the change-request flow. Alerts follow the organization's full escalation setup, including org-level integrations (webhooks, OpsGenie, org SMTP). - **`self_service`**: the customer owns the monitor. Customer users (including `readonly`-role portal logins) can **create, edit, and delete** their own self-service monitors, bounded by a package quota. Alerts go to the **customer's recipients only**. Org-level integration channels are skipped. Existing monitors were classified `managed`, so nothing changed for them until you explicitly flip a monitor. ## Who can do what | Action | Customer portal user | Organization admin | |---|---|---| | View a monitor | ✓ (own customer scope) | ✓ | | Edit/delete a `self_service` monitor | ✓ (own monitors) | ✓ | | Edit/delete a `managed` monitor | ✗, unless the customer has the `canEditManaged` exception | ✓ | | Create monitors | ✓ as `self_service`, if allowed and within quota | ✓ (any class) | | Change a monitor's class (`managed` ⇄ `self_service`) | ✗, always organization-only | ✓ | | Request a change / request managed status | ✓ (change request) | approves/rejects | Customers can never grant themselves rights: a customer-scoped API caller's writes to permission fields are ignored server-side, and flipping the class of a monitor is rejected with `403` (`managementTypeOrgOnly`). ## Permissions and inheritance Self-service behavior is configured at two tiers with a *null-means-inherit* model: 1. **Package config** (`PATCH /api/package-configs/:packageType`) sets the defaults for every customer on the package: `allowSelfService` (default `false`) and `maxSelfServiceUrls` (default `0`), plus the channel-permission defaults `enableEmailAlerts`, `enableSmsAlerts`, `enableWebhookAlerts`, `enableIntegrationAlerts`, `enablePostRequestEscalation`. 2. **Customer overrides** (`POST`/`PATCH /api/customers`) can set the same fields per customer. `null` (or omitting the field) means *inherit from the package config*. The per-customer `canEditManaged` flag additionally allows a specific customer to edit `managed` monitors without owning them. Resolution is always: customer value → package default → platform default, and it fails closed (absence = least privilege). ## The self-service quota `maxSelfServiceUrls` bounds a customer's **total** number of `self_service` monitors **across all monitor types**: five self-service websites plus three self-service ICMP monitors count as eight. When the quota is reached, creating another self-service monitor (or flipping an existing monitor to `self_service`) fails with `403` (`selfServiceQuotaReached`). ## Status pages Status pages with a customer carry the same `managementType` and follow the same rules: customer users (also `readonly`) and customer-bound tokens change only `self_service` pages of their customers, `managed` pages only with `canEditManaged`, and they create pages as `self_service` only when self-service is allowed. Readonly users never delete a page. The design stays with the roles `admin` and `editor`: `readonly` reads it on every page in scope but does not change it, not on its own `self_service` pages either. Change requests do not cover status pages yet. Pages without a customer belong to the organization and have no ownership class. See [Status Pages](/api/status-pages). ## Change requests For `managed` monitors, the portal shows a **Request change** action instead of edit controls. A request has a `kind`: - `change`: free-text ask ("please raise the check interval"). - `request_managed`: the customer asks the organization to take over responsibility for a monitor. Accepting this request flips the monitor to `managed` automatically… ### Monitoring Types URL: https://docs.uptimeify.io/monitoring/monitoring-types Description: Uptimeify supports a wide range of monitor types: from HTTP uptime, keyword, and SSL checks to DNS, network services, and synthetic browser flows. Pick the type that matches what you need to watch. Summary: ## Website & HTTP HTTP/HTTPS availability and status-code checks for your websites. Verify expected text is present (or absent) in the response body. Alert when a site responds slower than your threshold. Track the response payload size and catch unexpected bloat. Confirm HTTP correctly redirects to HTTPS (with HSTS). Catch expiring or invalid TLS certificates before they break trust. ## Network & Services Ping a host to check reachability and packet loss. Check that mail servers accept connections on the SMTP port. Monitor inbound mail retrieval services. Verify SSH endpoints are listening and reachable. Check that any raw TCP port (databases, caches, queues) is open and accepting connections. Check that FTP servers respond on their configured port. ## DNS & Domain Watch A, AAAA, MX, TXT, CNAME and other records for changes. Detect when your IPs land on DNS blocklists. Get warned well before a domain registration lapses. ## Advanced Be alerted when a scheduled job stops checking in. Synthetic browser flows that test real user journeys. ### DNS Monitor URL: https://docs.uptimeify.io/monitoring/monitoring-types/dns Description: The DNS Monitor checks DNS responses for a hostname (e.g. deinkunde.com) on a fixed interval. This helps you detect unexpected record changes (A/AAAA), missing MX records, or TXT changes (SPF/DMARC / domain verification). Summary: ## How it works - We resolve the selected **record types (RRTypes)** (e.g. `A`, `AAAA`, `MX`, `TXT`). - Optionally, we compare the resolved values against your **Expected Values**. - Depending on your trigger settings, we can create incidents/alerts for: - **Resolve Error** (e.g. `NXDOMAIN`, timeout) - **Mismatch** (resolved values differ from Expected Values) ## Configuration ### Basic settings - **Hostname**: Hostname only, without protocol or path (e.g. `deinkunde.com`, not `https://deinkunde.com/path`). - **Check interval**: How often to check (e.g. every 30 minutes). - **Status**: - `active`: checks run normally. - `maintenance`: checks still run, but alerting may be dampened depending on alert logic. - `disabled`: checks do not run. ### DNS checks - **RRTypes**: Comma-separated list, e.g. `A, AAAA, MX, TXT`. - **Match mode**: - `exact`: values must match exactly. - `contains`: expected values must be contained in the response. - **Expected values**: a list per RRType (one value per line). Empty fields mean “do not validate”. - **Triggers**: - `resolveError`: alert on DNS resolve errors. - `mismatch`: alert when Expected Values do not match. ## Monitoring locations DNS checks run from our monitoring locations. If a monitor does not specify its own restrictions, (if configured) the **customer-level allowed countries** apply. ### DNSBL Monitoring URL: https://docs.uptimeify.io/monitoring/monitoring-types/dnsbl Description: Monitor the reputation of your IP addresses on blocklists. Summary: **Status: Lab** This feature is currently in the **Lab phase**. This means we are still actively optimizing intervals and the selection of lists. DNSBL (DNS-based Blocklist) Monitoring regularly checks whether your server's IP address is listed on one of the known "Blacklists" (Blocklists/RBLs). Being listed on such a list often has serious consequences for email delivery (mails land in spam or are rejected). ## How it works We use our own open-source engine **[uptimeify-dnsbl](https://www.npmjs.com/package/uptimeify-dnsbl)** to check your IP address against over 50 international spam databases. ### Check Interval Currently, we perform the check **every 180 minutes (3 hours)**. - **Reason**: DNSBL operators often block excessive queries ("Rate Limiting"). A 3-hour rhythm is a good compromise between timeliness and "Good Citizenship" towards list operators. - *Note*: If there is a real need for more frequent checks, please contact us. ## What happens if a match is found? If we find your IP on a list (e.g., Spamhaus, Barracuda, SORBS): 1. **Notification**: You receive an alert via your configured channels. 2. **Details**: We show you the specific reason (e.g., "Listed in SBL" or "Dynamic IP Range"). 3. **Solution**: Where available, we provide a direct **Delisting Link** through which you can request removal from the list operator. ## Supported Lists We query a curated list of reliable providers. A complete overview can be found on the page [Used Lists](/monitoring/monitoring-types/dnsbl/lists). ### Used RBL Lists URL: https://docs.uptimeify.io/monitoring/monitoring-types/dnsbl/lists Description: We currently monitor your IP addresses against the following lists. This selection covers the most important and reliable international anti-spam databases. Summary: We use **[uptimeify-dnsbl](https://www.npmjs.com/package/uptimeify-dnsbl)** for this. ## Spamhaus Project *Probably the most important RBL worldwide.* - Spamhaus ## Other Important Lists - Barracuda (BRBL) - SpamCop - SORBS (Aggregate) - UCEPROTECT (Level 1, 2) - Hostkarma - Backscatterer - Invaluement SIP - SpamCannibal - DroneBL - Spam Eating Monkey (SEM-BLACK) - URIBL Black - RV-SOFT Technology - ZapBL - Suomispam Reputation - Kempt.net - Korea Services - NiX Spam - Passive Spam Block List (PSBL) - InterServer RBL - all.s5h.net - Abuse.ch (Combined, Drone, Spam) - 0spam (RBL, Blocklist) - Singular TTK PTE - SpamRats (Spam, Dyna, NoPtr) - Spamsources Fabel - Virus RBL JP - Woody's SMTP Blacklist - WPBL - Gweep (Proxy, Relays) - Digibase Spambot - Lashback UBL - WormRBL - Team Cymru Bogons - Nether.net Relays - Imp.ch Spam RBL - Mailspike Z - Anonmails.de - Pedantic.org - GBUdb Truncate ## Usage Notes We perform the queries in an "Aggregated" manner. This means we do not query each list individually one after the other, but parallelized and optimized to keep response time low and avoid timeouts. ### Domain Expiry Monitoring URL: https://docs.uptimeify.io/monitoring/monitoring-types/domain-expiry Description: An expired domain is one of the most severe incidents that can happen to a website. Once a domain expires, the entire online presence becomes unreachable, and in the worst case, the domain is registered by a third party. Our Domain Expiry Monitoring helps you proactively prevent this. Summary: ## How it works We use the **RDAP protocol** (Registration Data Access Protocol), the modern successor to WHOIS, to query the registration data of your domains directly from the responsible registries. RDAP delivers structured, reliable data and is supported by all major TLDs. ### Check Interval Currently, we perform the check **every 12 hours** (configurable via environment variable). - **Reason**: Domain registration data changes infrequently. A 12-hour rhythm provides timely detection while remaining respectful towards registry rate limits. - *Note*: If there is a real need for more frequent checks, please contact us. ## Two monitoring paths Domain Expiry Monitoring works through two independent channels: ### 1. Website-based checks If the **Domain Expiry Check** is enabled for a website, we automatically extract the domain from the URL and check its expiry date. Results are stored alongside the regular monitoring data. ### 2. Registered customer domains Domains can also be registered independently in the **Admin → Domains** section. This is useful for: - Domains that are not actively monitored as websites (e.g., parked domains, mail-only domains). - Tracking domains with individual warning thresholds per domain. - Per-domain notification overrides (separate email/phone contacts). ## Thresholds Two configurable thresholds determine when alerts are triggered: | Threshold | Default | Purpose | |---|---|---| | **Warning** | 30 days | Early heads-up that renewal is due soon. | | **Critical** | 7 days | Urgent alert: domain expires within days. | These thresholds can be configured individually per website or per registered domain. ## What happens when a threshold is breached? 1. **Warning**: You receive an alert via your configured notification channels when the domain enters the warning window. 2. **Critical**: An urgent alert is triggered if the domain expires within the critical threshold. 3. **Expired**: If the domain has already expired, we flag it immediately. 4. **Recovery**: When a domain is renewed and no longer within the warning window, open incidents are automatically resolved and a recovery notification is sent. ## Monitored Data For each domain, we record and display: - **Expiry Date**: When the domain registration expires. - **Registrar**: Which registrar manages the domain (e.g., "INWX", "Hetzner", "GoDaddy"). - **Days Until Expiry**: Calculated in real time. - **Current Status**: OK, Warning, Critical, or Expired. - **Last Checked**: Timestamp of the most recent RDAP lookup. ## Supported TLDs RDAP is supported by all major gTLDs (.com, .net, .org, etc.) and many ccTLDs (.de, .at, .ch, .nl, .uk, etc.). If a TLD is not supported by RDAP, we skip the check silently. No false alerts are generated. ## Troubleshooting If we report a domain expiry issue: 1. Check with your registrar whether the domain is set to **auto-renew**. 2. Verify that the payment method on file with your registrar is still valid. 3. For domains managed by third parties, confirm that the responsible person is aware of the upcoming renewal. ### FTP Monitor URL: https://docs.uptimeify.io/monitoring/monitoring-types/ftp Description: The FTP Monitor checks whether your FTP service is reachable and responsive. This helps detect outages on file transfer infrastructure used by legacy integrations, batch exports, or partner uploads. Summary: ## How it works - We connect to your FTP endpoint and verify that the service responds. - If the server cannot be reached or does not respond within the configured timeout, the check fails. ## Configuration ### Basic settings - **Hostname**: Hostname only, without protocol or path. - **Port**: Optional (default is typically 21). - **Check interval** and **Timeout**. - **Status**: `active`, `maintenance`, `disabled`. ### Advanced settings If your server requires authentication or encryption (e.g. FTPS), advanced options can be configured via the monitor settings. ### Monitoring locations FTP checks run from our monitoring locations. Monitor-level **Allowed Check Countries** (or customer-level defaults) control which locations are used. ### Port-only mode (no credentials) By default (**Check Mode**: `protocol`), the monitor connects to your FTP endpoint and verifies that the service responds as expected. Set **Check Mode** to `tcp` to skip that protocol validation. The monitor only opens a bare TCP connection to `hostname:port`, without any FTP handshake, and no credentials are required or stored. Use `tcp` mode when you only need to confirm the port is reachable. ### Heartbeat Monitoring (Cron) URL: https://docs.uptimeify.io/monitoring/monitoring-types/heartbeat Description: Heartbeat monitoring (also known as Cron Monitoring) works in reverse: instead of us checking your server, your server (or script) notifies us that it is alive. Summary: This is perfect for monitoring: - **Daily Backups:** Ensure your database backups actually ran. - **Background Jobs:** Monitor workers, import scripts, or periodic tasks. - **Intranet Devices:** Monitor devices behind a firewall that can send outbound requests. ## How it works 1. You create a **Heartbeat Monitor** in the dashboard. 2. We give you a unique **Heartbeat URL**. 3. You configure your script (Cronjob, Worker) to call this URL when it finishes successfully. 4. We expect a ping within your configured **Interval** (plus a **Grace Period**). 5. If we don't receive a ping in time, we send an alert: "Heartbeat missing", with the expected interval, the grace period, the time of the last ping and how long it is overdue, e.g. `Heartbeat missing: expected every 30 min + 5 min grace, last ping 2026-10-28T10:00:00.000Z, overdue by 12 min`. 6. While an incident is open, the next ping starts the recovery evaluation right away instead of waiting for the next scheduled run. ## Configuration ### Expected Interval How often do you expect the ping? - *Example:* For a daily backup, set this to **24 hours** (1440 minutes). - *Example:* For a minutely worker, set this to **1 minute**. - *Example:* For a monthly report job, set this to **30 days** (43200 minutes). - The interval accepts 1 to 43200 minutes (30 days). Unlike actively scheduled monitors, which we poll and therefore cap at 24 hours, a heartbeat only waits, so a long interval costs nothing. ### Grace Period How much delay is acceptable? - *Example:* If your backup usually takes 10 minutes but sometimes 30, set the Grace Period to **30 minutes**. - We will only alert if `Last Ping Time + Interval + Grace Period < NOW`. ### Expected state By default a heartbeat alerts when pings stop. You can turn this around: on the create and edit page, under **Alert when …**, choose **… a heartbeat arrives**. Use this for jobs that only ping when something went wrong (e.g. an error handler). - Every ping then counts as a failure and opens an incident. - The incident resolves once no ping has arrived for the interval plus the grace period. - In the API the field is `expectedState`: `up` (default, alert when pings stop) or `down` (alert when a ping arrives). ## Usage Examples ### Linux Cronjob (Backup Script) ```bash #!/bin/bash # Run backup ... pg_dump dbname > backup.sql # If successful, ping the heartbeat if [ $? -eq 0 ]; then curl -m 10 --retry 3 https://ping.uptimeify.io/ping/YOUR_TOKEN fi ``` ### PowerShell (Windows) ```powershell # Run task... Write-Output "Task running..." # Ping Heartbeat Invoke-RestMethod -Uri "https://ping.uptimeify.io/ping/YOUR_TOKEN" ``` ### Node.js Worker ```javascript await doImport(); // Ping await fetch('https://ping.uptimeify.io/ping/YOUR_TOKEN'); ``` ### HTTPS Redirect Check URL: https://docs.uptimeify.io/monitoring/monitoring-types/https-redirect Description: Security and SEO are indispensable today. The HTTPS Redirect Check ensures that visitors accessing your website unencrypted via http:// are automatically redirected to the secure https:// version. Summary: ## Why is this important? - **Security**: Prevents Man-in-the-Middle attacks. - **SEO**: Search engines like Google prefer HTTPS and penalize sites without correct redirection. - **User Trust**: Users see the lock symbol in the browser. ## How it works This check is an option within the Uptime Monitor. When enabled: 1. We explicitly call the URL with `http://`. 2. We expect a status code `301` (Permanent Redirect) or `302` (Found) as well as `307/308`. 3. We check if the redirect target starts with `https://`. ## Configuration You can find this setting in the advanced options of your monitor: - **Enable HTTPS Redirect Check**: Enable this option to enforce the redirect. ### ICMP Monitor URL: https://docs.uptimeify.io/monitoring/monitoring-types/icmp Description: The ICMP Monitor checks whether a host is reachable on the network. This is ideal for infrastructure components that do not expose HTTP endpoints (e.g. routers, firewalls, VPN gateways, databases, or internal services). Summary: ## How it works - We send ICMP echo requests (“ping”) to your **hostname**. - The monitor is considered healthy when the target responds within the configured timeout. - We record latency and detect sustained reachability problems. ## Configuration ### Basic settings - **Name**: A human-friendly label. - **Hostname**: Hostname or IP address (no protocol, no path). - **Check interval**: How often to check. - **Timeout**: How long to wait for a response. - **Status**: - `active`: checks run normally. - `maintenance`: checks still run, but alerting may be dampened depending on alert logic. - `disabled`: checks do not run. ### Monitoring locations ICMP checks run from our monitoring locations. - If you set **Allowed Check Countries** on the monitor, checks run only from matching locations. - If the monitor has no restrictions, (if configured) the **customer-level allowed countries** apply. ### IMAP/POP Monitor URL: https://docs.uptimeify.io/monitoring/monitoring-types/imap-pop Description: The IMAP/POP Monitor verifies that your mail server is reachable for clients. This is useful for detecting authentication and connectivity issues that impact inbox access. Summary: ## How it works - We connect to your IMAP or POP endpoint and validate that the service responds. - If the server cannot be reached or does not respond in time, the check fails. ## Configuration ### Basic settings - **Hostname**: Hostname only, without protocol or path. - **Port**: Optional (commonly 143/993 for IMAP, 110/995 for POP). - **Check interval** and **Timeout**. - **Status**: `active`, `maintenance`, `disabled`. ### Advanced settings Protocol selection (IMAP vs POP) and other advanced options (e.g. encryption/auth requirements) can be configured via the monitor settings. ### Monitoring locations IMAP/POP checks run from our monitoring locations. You can restrict execution using **Allowed Check Countries** (monitor-level) or by using the customer-level defaults. ### Port-only mode (no credentials) By default (**Check Mode**: `protocol`), the monitor logs in to your IMAP or POP endpoint and validates the connection. Set **Check Mode** to `tcp` to skip authentication entirely. The monitor only opens a bare TCP connection to `hostname:port`, without an IMAP/POP handshake or login, and no credentials are required or stored. Use `tcp` mode when you only need to confirm the port is reachable. Unlike SSH, SMTP, and FTP, **IMAP/POP requires an explicit Port when Check Mode is `tcp`**. Since there's no way to infer IMAP vs. POP without one, the monitor can't fall back to a protocol default port. ### Keyword Monitor URL: https://docs.uptimeify.io/monitoring/monitoring-types/keyword Description: Sometimes a page is technically \\\"online\\\" (Status Code 200) but doesn't show the desired content: for example, a white page, a database error message, or \\\"Out of Stock\\\". The Keyword Monitor (also called \\\"Content Monitor\\\") solves this problem. Summary: ## How it works The Keyword Monitor downloads the HTML body of your page and searches it for a specific text (string). It is useful for ensuring that: - The database connection is working (check for dynamic content). - The CMS renders correctly. - No maintenance mode is displayed. ## Configuration Modes You can run the monitor in two modes: ### 1. "Must Contain" (Keyword Present) Alert if the word is **NOT** found. - **Use Case**: Check for "Welcome", "Imprint", or the company name in the footer. - **Example**: Check for the name of a bestseller product on a shop page. ### 2. "Must Not Contain" (Keyword Absent) Alert if the word **IS** found. - **Use Case**: Check for error messages. - **Examples**: "MySQL Error", "404 Not Found" (in text), "Hacked by", "Maintenance Mode". ## Setup Steps 1. Create a new monitor or edit an existing one. 2. Under "Advanced Settings", select the **Keyword Check** option. 3. Enter the search term (Case-sensitive!). 4. Save the monitor. ### Page Size Check URL: https://docs.uptimeify.io/monitoring/monitoring-types/page-size Description: The Page Size Check monitors the size of your website's HTML response content (body) in bytes. Unexpected changes in file size can indicate serious issues that are missed by a pure status code check (200 OK). Summary: ## Use Cases - **Hacks / Defacements**: Attackers often inject code, significantly increasing the page size. - **Empty Pages**: A database error could cause only the header to render (page suddenly very small), although the server reports Status 200. - **Performance**: Accidentally including huge scripts or CSS files in the HTML. ## Configuration You can define thresholds: ### Min Page Size Alert if the page is smaller than X bytes. - *Recommendation*: Set this to approx. 80-90% of your page's normal size to detect partially empty renderings. ### Max Page Size Alert if the page is larger than Y bytes. - *Recommendation*: Protects against "code bloat" or injections. The check is considered failed if the actual size is outside this range. ### Playwright Monitor URL: https://docs.uptimeify.io/monitoring/monitoring-types/playwright Description: For critical processes like Login, Checkout, or Registration, a simple HTTP check is often insufficient. The Playwright Monitor loads your website in a real browser (Headless Chromium) and executes a script defined by you. Summary: This simulates a real user and uncovers JavaScript errors, broken buttons, or UI issues. ## How it works We execute your Playwright script in our secure cloud environment. - **Success**: The script runs to completion without errors. - **Error**: An `expect` check fails or a timeout occurs. We automatically save a **screenshot** and the error message. ## Example: Testing Login Here is a simple script to test a login process: ```javascript test('User can login', async ({ page }) => { // 1. Navigation await page.goto('https://app.deinkunde.com/login'); // 2. Fill form (Using Env Variables) await page.fill('input[name="email"]', 'monitor-user@deinkunde.com'); await page.fill('input[name="password"]', process.env.MONITOR_PASSWORD); // 3. Submit await page.click('button[type="submit"]'); // 4. Verification (Wait for dashboard element) await expect(page).toHaveURL(/dashboard/); await expect(page.locator('.welcome-message')).toContainText('Hello'); }); ``` ## Environment Variables (Secrets) You should never store passwords, API keys, or sensitive data directly in the script ("hardcoding"). Instead, use **Environment Variables**. ### Setup 1. Navigate to **Monitor Settings**. 2. Open the **Advanced Settings** section. 3. Find the **Environment Variables** section. 4. Enter the Key and Value. - Example Key: `PASSWORD` - Example Value: `SecretPassword123!` ### Usage in Script In Playwright code, access values via `process.env.KEY`. The values are injected into the secure worker environment only at runtime. ```javascript test('Secure Login', async ({ page }) => { await page.goto('https://deinkunde.com/login'); // Secure access via process.env await page.fill('#password', process.env.PASSWORD); await page.click('#submit'); }); ``` ### Security - Values are stored **encrypted** in our database. - They are not visible in plain text in the frontend editor after saving (depending on permissions). - They do not appear in the screenshot log (unless you explicitly `console.log` them). ## Tips for Stable Tests - Use `data-testid` attributes for selectors where possible. ### Response Time Check URL: https://docs.uptimeify.io/monitoring/monitoring-types/response-time Description: In addition to pure availability, speed is crucial for user experience. The Response Time Check measures how long your server takes to respond to a request. Summary: ## What is measured? We typically measure the **Time to First Byte (TTFB)** as well as the time for the complete transfer of the HTML document. ## Configuration You can set thresholds for warnings: - **Threshold (ms)**: If the response time exceeds this value (e.g., 2000ms), an alarm is triggered or the status is marked as "Degraded", depending on configuration. ## Analysis In the monitor details, you will find charts showing the development of response time over time. This helps you to: - Identify performance bottlenecks at specific times (e.g., during backups). - See the impact of code deployments on speed. ### SMTP Monitor URL: https://docs.uptimeify.io/monitoring/monitoring-types/smtp Description: The SMTP Monitor verifies that your SMTP server is reachable and responsive. This helps you detect outages of outbound mail gateways and mail delivery infrastructure before users report missing emails. Summary: ## How it works - We connect to your SMTP server and validate that it responds as expected. - If the server cannot be reached or does not respond in time, we mark the check as failed. ## Configuration ### Basic settings - **Hostname**: Hostname only, without protocol or path. - **Port**: Optional. Use your SMTP port (commonly 25 / 587 / 465). - **Check interval** and **Timeout**. - **Status**: `active`, `maintenance`, `disabled`. ### Advanced settings Depending on your use case, advanced options (e.g. encryption/auth requirements) can be configured via the monitor settings. ### Monitoring locations SMTP checks run from our monitoring locations. You can restrict execution using **Allowed Check Countries** (monitor-level) or by using the customer-level defaults. ### Port-only mode (no credentials) By default (**Check Mode**: `protocol`), the monitor connects to your SMTP server and validates that it responds as expected. Set **Check Mode** to `tcp` to skip that protocol validation. The monitor only opens a bare TCP connection to `hostname:port`, without any SMTP handshake, and no credentials are required or stored. Use `tcp` mode when you only need to confirm the port is reachable. ### SSH Monitor URL: https://docs.uptimeify.io/monitoring/monitoring-types/ssh Description: The SSH Monitor checks whether your SSH service is reachable. It is commonly used to detect firewall issues, network outages, or server crashes affecting administrative access. Summary: ## How it works - We attempt to connect to your SSH service. - If the server cannot be reached, rejects connections unexpectedly, or times out, the check fails. ## Configuration ### Basic settings - **Hostname**: Hostname or IP address. - **Port**: Optional (default is typically 22). - **Check interval** and **Timeout**. - **Status**: `active`, `maintenance`, `disabled`. ### Monitoring locations SSH checks run from our monitoring locations. Use **Allowed Check Countries** to limit where checks run from. ### Port-only mode (no credentials) By default (**Check Mode**: `protocol`), the monitor logs in over SSH with the credentials you provide and verifies a successful handshake/login. Set **Check Mode** to `tcp` to skip authentication entirely. The monitor only opens a bare TCP connection to `hostname:port`, without attempting an SSH handshake or login, and no credentials are required or stored. Use `tcp` mode when you only need to confirm the port is reachable (e.g. a firewall or network check) without giving Uptimeify SSH credentials. ### SSL Monitor URL: https://docs.uptimeify.io/monitoring/monitoring-types/ssl Description: Expired SSL certificates are a common cause of downtime and loss of user trust. Browsers display warnings like \\\"Connection not secure\\\". Our SSL Monitor helps you proactively prevent this. Summary: ## How it works The SSL Monitor regularly checks the configuration of your TLS/SSL certificate. It is often integrated into the Uptime Monitor but can also be configured separately. ## Monitored Metrics ### 1. Expiration (Expiry) This is the most critical check. We alert you well before the expiration date so you can renew the certificate. - **Notification**: By default, we remind you **30, 14, 7, and 1 day(s)** before expiration (configurable). ### 2. Validity & Chain of Trust We check if the certificate: - Is signed by a trusted Root CA. - Has not been revoked (OCSP/CRL Check). - Is issued for the correct hostname (domain). ## Troubleshooting If we report an SSL error: 1. Check the expiration date. 2. Check if "Intermediate Certificates" are correctly installed (Chain incomplete error). 3. Ensure the hostname in the certificate (CN or SAN) matches the monitored URL. ### TCP Port Monitor URL: https://docs.uptimeify.io/monitoring/monitoring-types/tcp-port Description: The TCP Port Monitor checks whether a raw TCP port is open and accepting connections. It is commonly used for databases, caches, message queues, and other non-HTTP services that don't speak a protocol we have a dedicated monitor for. Summary: ## How it works - We attempt to open a TCP connection to your `hostname:port`. - If the connection cannot be established or times out, the check fails. - If you configure **Expect Banner**, we also verify that the raw bytes received right after the handshake contain that substring (e.g. `+PONG` for Redis, `220` for an SMTP banner). Otherwise the check fails even though the port is open. ## Configuration ### Basic settings - **Hostname**: Hostname or IP address (no protocol, no path). - **Port**: Required. Unlike other monitor types, there is no default port. You must specify the exact port to connect to (e.g. `6379` for Redis, `5432` for PostgreSQL, `27017` for MongoDB). - **Expect Banner**: Optional substring the worker must find in the bytes received immediately after the TCP handshake. - **Check interval** and **Timeout**. - **Status**: `active`, `maintenance`, `disabled`. ### Expected state By default the check fails when the port is not reachable. For ports that must stay closed (e.g. a maintenance or debug port, or a database that should never be reachable from the internet), choose **… the port is reachable** under **Alert when …** on the create and edit page. Then: - A successful connection counts as a failure and opens an incident. - Connection refused, timeout, reset and host or network unreachable count as closed, so the check succeeds. - DNS resolution errors and other errors still fail, so a typo in the hostname does not look green. - **Expect Banner** is ignored in this mode. - In the API the field is `expectedState`: `up` (default) or `down`. ### Monitoring locations TCP checks run from our monitoring locations. Use **Allowed Check Countries** to limit where checks run from. ### No credentials TCP Port monitors carry no credentials or authentication. They only verify that the port accepts connections (and optionally that the initial banner matches). For services that require authentication before you can confirm they're healthy, use a protocol-specific monitor (e.g. SSH, SMTP, IMAP/POP) where one exists. ### Uptime Monitor URL: https://docs.uptimeify.io/monitoring/monitoring-types/uptime Description: The Uptime Monitor is the core of your monitoring strategy. It regularly checks if your website or API endpoint is accessible to your customers. We recommend setting up at least one Uptime Monitor for every publicly accessible page. Summary: ## How it works We send HTTP or HTTPS requests to your URL at the interval you choose (e.g., every 30 seconds or every minute). We consider the monitor "Online" if: 1. The server responds (no timeout). 2. The **Status Code** matches expectations (default `2xx`, e.g., 200 OK). If an error is detected, we verify it from nine European locations across Germany, Spain, France, Italy, Poland and Finland to avoid false alarms before sending a notification. ## Create a website ### Where is this in the UI? In the dashboard, navigate to **Websites** and click **New website** / **Create website**. ### Name Choose a name that is easy to recognize for your team (e.g. "Marketing Website", "Shop API", "Customer Portal"). ### URL Uptimeify **automatically prepends `https://`** if you enter a plain hostname (e.g. `deinkunde.com`), so you don't need to type the protocol yourself, but you can always paste the full URL (e.g. `https://deinkunde.com`) as well. Tips: - Prefer the canonical target URL (usually `https://…`). - If you want to verify HTTP→HTTPS behavior, also use the **HTTPS Redirect** monitor type. ### Status You can keep a website active or temporarily disable it (e.g. during migrations). A disabled website is not monitored. ## Configuration ### Basic Settings - **URL**: The full address (e.g., `https://deinkunde.com`). - **Check Interval**: How often to check (e.g., 60s). ### Advanced Settings - **Expected Status Codes**: By default, we check for `200-299`. You can adjust this, e.g., to `200,301,302` if redirects should be considered a success. - **Timeout**: Maximum time to wait for a response (Default: 30s). - **HTTP Method**: Default is `GET`. You can also choose `HEAD`, `POST`, `QUERY`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`. `QUERY` is safe and idempotent like `GET` but carries a request body, for read-only endpoints that expect a search, a filter or a GraphQL-style query. The body field behaves exactly as it does for `POST` and is stored encrypted. Not every server implements `QUERY` yet: a target that answers `405` is telling you the truth about that endpoint, and the monitor reports it like any other unexpected status. - **Request Body & Headers**: Send JSON data or authentication tokens (e.g., `Authorization: Bearer ...`). ## Optional checks When configuring an Uptime Monitor, you can enable additional checks alongside the basic availability test: - **SSL**: Monitor certificate validity and expiration date → see [SSL Monitor](/monitoring/monitoring-types/ssl) - **Response Time**: Set performance thresholds and get alerted when your site slows down (see [Response Time](#response-time) below) - **Keyword / Content Validation**: Verify that specific content is present in the response body - **Page Size**: Alert on unexpected size changes that may indicate missing resources or bloat ## Common pitfalls ### URL vs. hostname (DNS/ICMP) The Uptime Monitor accepts a plain hostname (Uptimeify adds `https://` automatically) or a full URL. Some other monitor types work with a **hostname without protocol** and do not perform HTTP requests. - DNS Monitor: hostname without protocol (e.g. `deinkunde.com`) → see [DNS Monitor](/monitoring/monitoring-types/dns) - ICMP Monitor: hostname without protocol (e.g. `server.deinkunde.com`) → see [ICMP Monitor](/monitoring/monitoring-types/icmp) ### Authentication / bot protection If your site uses Basic Auth, token auth, or bot protection, a simple HTTP check may fail. - Configure auth headers or Basic Auth credentials in the **Request Headers** field. - For complex login flows, **Playwright** monitors are often the more robust choice. ## Response Time In addition to status, we also record the response time (Time to First Byte + Download). - You can configure alerts if the response time exceeds a threshold (e.g., > 2000ms), even if the status is 200 OK. ## Next steps - Investigate outages and view history: [Incidents](/incidents) ### Using Tags URL: https://docs.uptimeify.io/monitoring/tags Description: Organize and filter monitors with color-coded tags across all monitor types. Summary: Tags let you label any monitor, website, DNS, ICMP, SMTP, SSH, FTP, or IMAP/POP, with one or more color-coded badges. You can then filter every monitor list by tag and instantly see which monitors belong to a group (e.g. "Production", "Client A", "Staging"). ## Creating Tags Open **Settings → Tags** and click **New Tag**. Provide: - **Name**: a short label, up to 50 characters. - **Color**: choose from the fixed palette: `slate`, `red`, `amber`, `green`, `teal`, `blue`, `indigo`, `violet`, `pink`, or `gray`. Tags are organization-scoped: every member with sufficient permissions can see and use them. ### Readonly member rule Readonly members **can** create tags, but those tags are visible only to themselves. A readonly member cannot see, update, or delete tags created by other users. They can assign their own tags to any monitor they have read access to. ## Color Palette | Key | Color | |-----|-------| | `slate` | Slate / neutral gray | | `red` | Red | | `amber` | Amber / orange | | `green` | Green | | `teal` | Teal | | `blue` | Blue | | `indigo` | Indigo | | `violet` | Violet / purple | | `pink` | Pink | | `gray` | Gray | ## Assigning Tags Tags can be assigned in two places: ### From the monitor list (inline) In any monitor list (Websites, DNS, ICMP, etc.) find the **Tags** column. Click the tag chip area on a row to open the tag picker and toggle tags on or off for that monitor. ### From the monitor detail page Open a monitor's detail page and locate the **Tags** section. Use the tag picker to add or remove tags. Changes are saved immediately. ## The Tags Column The Tags column is visible by default in every monitor list. To get a more compact view, toggle the column off using the **Columns** menu at the top of the list. Your preference is saved per list. ## Filtering by Tag At the top of any monitor list, open the **Filter** menu and select one or more tags. The list narrows to show only monitors that carry **all** of the selected tags (AND logic). To clear the filter, deselect all tags or click **Reset filters**. ## Managing Tags Go to **Settings → Tags** to see the full tag list. From there you can: - **Edit** a tag's name or color (owner or admin only). - **Delete** a tag: this removes the tag from every monitor it was assigned to (cascade delete). ## API Reference See the [Tags API](/api/tags) for programmatic access to create, update, delete, and assign tags. ## Status Pages ### Status Pages URL: https://docs.uptimeify.io/status-pages Description: Status pages let you communicate service health to your customers transparently: live overall state, a per-service breakdown, and a short history of recent incidents and maintenance. Each page is fully brandable and can run on your own domain (e.g. status.deinkunde.com). Summary: 8 layouts, color schemes, accent color, custom title, and toggles for what to show. Serve a page on `status.deinkunde.com` with DNS verification and automatic HTTPS. Create, update, design, and manage domains programmatically. ## What a status page shows - **Overall state**: a single banner: Operational, Degraded, or Maintenance. - **Services**: the customer's monitored websites and service monitors, each with its own state. - **Components**: rows you add explicitly, either a monitor or an entry you maintain by hand (for example a third-party provider), optionally in groups. Managed through the [Status Pages API](/api/status-pages). - **Uptime statistics**: optional per-service uptime percentages. - **Recent history**: optional list of recent incidents and maintenance windows. ### How the public state is derived Uptimeify computes each service's public state from two live signals. It never exposes raw check data: | Condition | Public state | |-----------|--------------| | One or more **open incidents** | **Degraded** | | **Active maintenance window** and no open incidents | **Maintenance** | | Neither | **Operational** | The overall banner reflects the worst state across all services. See [Incidents](/incidents) and [Maintenance](/maintenance) for how those signals are produced. ## Create a status page In the app, go to **Dashboard → Status Pages → Create**. A page belongs to one **customer** and shows that customer's services. Through the API a page can also be created without a customer: it then belongs to the whole organization, shows only its explicit components and is managed by organization-wide roles only. | Setting | Description | |---------|-------------| | **Customer** | Required. The customer whose services the page displays. | | **Public name** | The page title shown to visitors. | | **Slug** | Used for the friendly URL. Auto-generated from the name; lowercase letters, numbers, and hyphens. | | **Description** | Optional intro text shown under the title. | | **Visibility** | `public` (anyone can view) or `customer_members_only` (login + access to the customer required). | | **Published** | Toggle off to hide the page without deleting it. | You can do all of this via the [API](/api/status-pages/create-status-page) too. ## URLs Every status page is reachable at: - `/status/`: friendly URL based on the configured slug. - `/status/`: stable URL based on the page ID (always available, even if the slug changes). With a [custom domain](/status-pages/custom-domains) configured and active, the page is also served at the apex of that hostname, e.g. `https://status.deinkunde.com/`. ## Visibility & publishing - **`public`**: the page is reachable by anyone with the link. Best for customer-facing status. - **`customer_members_only`**: visitors must be logged in and have access to the customer. Best for internal or NDA-bound services. - **Published** is independent of visibility: an unpublished page returns *not found* (HTTP 404) regardless of visibility, which is useful while you are still setting it up. Signed-in members of your own organization still see it at its `/status/` address, with a "Preview, not public" banner, so you can check it before publishing. ## Recent history The **Recent History** section is controlled by two independent toggles: - **Show recent incidents** - **Show recent maintenance** These only affect the *history list*. Live indicators (such as a service currently being in maintenance) are always shown, independent of these flags. The [design settings](/status-pages/design) additionally control the history time window (`historyDays`). ## Troubleshooting ### "Status page not found" - Confirm the page is **Published**. - If visibility is `customer_members_only`, you mus… ### Custom Domains URL: https://docs.uptimeify.io/status-pages/custom-domains Description: Connect a hostname like status.deinkunde.com to a status page so it runs entirely under your own brand. A hostname can be bound to exactly one status page, and the certificate is issued automatically once the domain is verified and active. Summary: ## How it works A custom domain moves through three states: 1. **Pending**: added, waiting for DNS verification. 2. **Verified**: the TXT record was found; ready to activate. 3. **Active**: the page is served on the hostname over HTTPS. ``` Add hostname → Add TXT record → Verify → Activate → Point CNAME (pending) (your DNS) (verified) (active) (traffic) ``` ## Step 1: Add the hostname In the app: **Dashboard → Status Pages → (page) → Custom Domain → Add**, enter `status.deinkunde.com`. Via the API: [Add Custom Domain](/api/status-pages/add-status-page-domain). Uptimeify returns a TXT verification record: - **TXT name**: `_verify-status.status.deinkunde.com` - **TXT value**: the token shown in the app / API response ## Step 2: Add the TXT record Create the TXT record in your DNS provider exactly as shown. Keep it in place. It is also re-checked over time. Domains verified before 13 May 2026 use the older record name `_uptimeify-verify.`. That record stays valid and keeps verifying; nothing to change. New domains always use the name shown above. DNS changes can take anywhere from a few minutes to a few hours to propagate. If verification fails immediately, wait and retry. ## Step 3: Verify Click **Verify** (or call [Verify Status Page Domain](/api/status-pages/verify-status-page-domain)). Uptimeify looks up the TXT record and checks the token matches. On success the domain becomes **Verified**. ## Step 4: Activate Click **Activate** (or call [Activate Status Page Domain](/api/status-pages/activate-status-page-domain)). The domain becomes **Active** and a TLS certificate is provisioned automatically (on-demand HTTPS): no certificate upload required. ## Step 5: Point traffic to Uptimeify Finally, point the hostname at Uptimeify so visitors actually reach the page. Add the CNAME shown in the app for `status.deinkunde.com`. Once DNS resolves, `https://status.deinkunde.com/` serves your status page. Keep both records in place: the **TXT** record (used for ongoing verification) and the **CNAME** (routes visitor traffic). If the TXT record disappears the weekly re-check reports it and we get in touch; your domain is never switched off automatically. ## Apex domains (example.com without a subdomain) A CNAME is not allowed on the apex of a zone, so `deinkunde.com` itself cannot simply point at Uptimeify like `status.deinkunde.com` can. Two ways work: - **Your DNS provider supports CNAME flattening, ALIAS or ANAME:** create that record type on the apex with the same target the app shows for the CNAME. Examples: Cloudflare (CNAME flattening, applied automatically to a CNAME on the apex), Bunny DNS (CNAME flattening), Amazon Route 53 (alias record), DNSimple (ALIAS record). The TXT record from step 2 stays as it is. - **Your provider offers none of these:** use a subdomain such as `www.deinkunde.com` or `status.deinkunde.com` as the custom domain and set up a redirect from the apex to it at your registrar or DNS provider. Do not point the apex at our IP addresses with **A or AAAA records**. Status pages are served from several frontends, and the addresses behind the CNAME target change when traffic fails over from one frontend to another. A hard-coded IP address does not follow that failover, so your page could go offline exactly when it is needed most. ## When changes show up Saved changes to the page (name, design, components, incidents) are live on the next reload, on your own domain as on `/status/`: the status page HTML is never cached (`Cache-Control: no-store`). Two things take a little longer on your own domain: - **Publishing, unpublishing and a new address** take up to 30 seconds, because each server remembers which page a hostname belongs to for that long. - **Badge, widget and feeds** may be cached for up to 60 seconds. An unpublished page answers with HTTP 404 on your own domain too, without a redirect to the… ### Design & Branding URL: https://docs.uptimeify.io/status-pages/design Description: Every status page has a visual design configuration. Edit it in the app under Dashboard → Status Pages → (page) → Design, or via the design API. Changes are merged: you only send the fields you want to change, and the rest keep their current values. Summary: ## Layouts Choose one of nine layout presets. They all show the same data (overall state, services, optional stats and history) but differ in structure and density. Preview each one live in the design editor. The design editor shows each layout under the name in the first column; the API and MCP use the value in the second. | Layout (design editor) | API value | Best for | |------------------------|-----------|----------| | Classic | `classic` | A prominent hero banner with the overall state, followed by the service list. | | Cards | `cards` | Each service rendered as a card in a responsive grid. | | Minimal | `minimal` | Stripped-back, text-first presentation with minimal chrome. | | Sleek | `sleek` | A modern hero banner with an accent-color gradient. | | Board | `board` | A dashboard-style board to see many services at a glance. | | Split | `split` | A full-width header with a two-column body (status next to history). | | Timeline | `timeline` | Emphasizes a chronological timeline of incidents and maintenance. | | Compact | `compact` | Dense layout that fits many services into little vertical space. | | Statusboard | `statusboard` | The default for every page without its own layout. Uptime bars per service across the whole history window, like a classic status board. | ### Screenshots All screenshots show the same demo page in the light color scheme, otherwise with default settings, 1280 x 900 px. #### Classic (`classic`) ![Status page in the Classic layout](/images/status-pages/layouts/classic.png) #### Cards (`cards`) ![Status page in the Cards layout](/images/status-pages/layouts/cards.png) #### Minimal (`minimal`) ![Status page in the Minimal layout](/images/status-pages/layouts/minimal.png) #### Sleek (`sleek`) ![Status page in the Sleek layout](/images/status-pages/layouts/sleek.png) #### Board (`board`) ![Status page in the Board layout](/images/status-pages/layouts/board.png) #### Split (`split`) ![Status page in the Split layout](/images/status-pages/layouts/split.png) #### Timeline (`timeline`) ![Status page in the Timeline layout](/images/status-pages/layouts/timeline.png) #### Compact (`compact`) ![Status page in the Compact layout](/images/status-pages/layouts/compact.png) #### Statusboard (`statusboard`) ![Status page in the Statusboard layout](/images/status-pages/layouts/statusboard.png) ## Appearance | Option | Values | Default | Description | |--------|--------|---------|-------------| | `colorScheme` | `light`, `dark`, `auto` | `auto` | `auto` currently renders like `light`. | | `accentColor` | hex color `#rrggbb` | `#6366f1` | Used for highlights, links, and gradients. | | `headerStyle` | `simple`, `centered`, `hero` | `simple` | How prominent the page header is. | | `fontFamily` | `system`, `mono` | `system` | `mono` gives a technical, monospaced look. | | `cardRadius` | `none`, `md`, `xl` | `md` | Corner rounding of cards and panels. | | `pageWidth` | `sm`, `md`, `lg`, `xl` | `lg` | Maximum content width. | ## Content & sections | Option | Type | Default | Description | |--------|------|---------|-------------| | `customTitle` | string (≤120) | - | Overrides the page title in the header. | | `customSubtitle` | string (≤200) | - | A subtitle shown under the title. | | `showUptimeStats` | boolean | `true` | Show per-service uptime percentages. | | `showServiceUrls` | boolean | `false` | Show each service's URL next to its name. | | `showLastChecked` | boolean | `false` | Show the "last checked" timestamp per service. | | `showHistory` | boolean | `true` | Show the recent history section. | | `historyDays` | number | - | How many days of history to include (bounded by the platform min/max). | | `showPoweredBy` | boolean | `true` | Show a "Powered by ``" line in the footer. It names **you**, never Uptimeify: with no product name set, the line is not rendered at all. | `showHistory` controls whether the history *section* is rendered. The separate **Show recent incidents** and **… ## Terraform ### Terraform & OpenTofu URL: https://docs.uptimeify.io/terraform Description: Manage monitors, incident management, status pages and users as code with the Uptimeify provider for OpenTofu and Terraform. Summary: Your monitoring, defined in code. Monitors, incident management, status pages and users live next to the infrastructure they watch, go through the same pull request review and roll out the same way for every customer. Drift shows up in the next `plan`, not in the next outage. The provider `uptimeify/uptimeify` works with **OpenTofu 1.11+** and **Terraform 1.11+**. Every resource is acceptance-tested against a real Uptimeify instance. Install the provider and create your first monitor. One configuration per client, scoped by its own token. Bring monitors you created in the dashboard under code. Write-only attributes, package limits and how updates are sent. ## Install ```terraform terraform { required_version = ">= 1.11" required_providers { uptimeify = { source = "uptimeify/uptimeify" version = "~> 0.5" } } } # endpoint and api_token fall back to UPTIMEIFY_ENDPOINT and UPTIMEIFY_API_TOKEN. provider "uptimeify" {} ``` The provider is published in the [OpenTofu registry](https://search.opentofu.org/provider/uptimeify/uptimeify/latest) and the [Terraform registry](https://registry.terraform.io/providers/Uptimeify/uptimeify/latest) under the same address. ## Provider configuration | Argument | Environment variable | Default | | --- | --- | --- | | `api_token` (String, Sensitive) | `UPTIMEIFY_API_TOKEN` | none, required | | `endpoint` (String) | `UPTIMEIFY_ENDPOINT` | `https://uptimeify.io` | `api_token` is an organization API token or a customer token, both start with `wsm_`. Create one in the dashboard under **Settings > API**, see [Generate an API token](/api/introduction/generate-api-token) and [Token scopes](/api/introduction/token-scopes-organization-vs-customer). Keep it in the environment or a secret store, not in the configuration. ## What you can manage Everything the Uptimeify API allows an API token to change. All names carry the `uptimeify_` prefix. | Area | Resources | | --- | --- | | Monitors | [`website`](/terraform/resources/website) (HTTP and heartbeat), [`dns_monitor`](/terraform/resources/dns_monitor), [`tcp_monitor`](/terraform/resources/tcp_monitor), [`icmp_monitor`](/terraform/resources/icmp_monitor), [`smtp_monitor`](/terraform/resources/smtp_monitor), [`ssh_monitor`](/terraform/resources/ssh_monitor), [`ftp_monitor`](/terraform/resources/ftp_monitor), [`imap_pop_monitor`](/terraform/resources/imap_pop_monitor) | | Organizing | [`tag`](/terraform/resources/tag), [`monitor_tag`](/terraform/resources/monitor_tag), [`custom_field`](/terraform/resources/custom_field), [`maintenance_window`](/terraform/resources/maintenance_window) | | Alerting | [`notification_channel`](/terraform/resources/notification_channel), [`escalation_config`](/terraform/resources/escalation_config) | | Customers | [`customer`](/terraform/resources/customer), [`customer_ip`](/terraform/resources/customer_ip), [`customer_domain`](/terraform/resources/customer_domain) | | Incident management | [`im_team`](/terraform/resources/im_team), [`im_team_member`](/terraform/resources/im_team_member), [`im_escalation_tier`](/terraform/resources/im_escalation_tier), [`im_schedule`](/terraform/resources/im_schedule), [`im_schedule_override`](/terraform/resources/im_schedule_override), [`im_team_override`](/terraform/resources/im_team_override), [`im_alert_source`](/terraform/resources/im_alert_source), [`im_routing_rule`](/terraform/resources/im_routing_rule), [`im_channel`](/terraform/resources/im_channel), [`im_outbound_integration`](/terraform/resources/im_outbound_integration), [`im_statuspage_rule`](/terraform/resources/im_statuspage_rule), [`im_service`](/terraform/resources/im_service), [`im_org_settings`](/terraform/resources/im_org_settings),… ### Customer tokens URL: https://docs.uptimeify.io/terraform/customer-tokens Description: Run one OpenTofu or Terraform configuration per client, each with its own customer-scoped API token and provider alias. Summary: API tokens come in two scopes. An **organization token** manages the whole organization. A **customer token** reaches only the customers it is scoped to: the right fit when you run monitoring for several clients. Details: [Token scopes](/api/introduction/token-scopes-organization-vs-customer). ## One configuration per client Give each client its own provider alias and customer token. A mistake in one client's code cannot touch another client's monitors. ```terraform variable "acme_token" { type = string sensitive = true } provider "uptimeify" { alias = "acme" api_token = var.acme_token } data "uptimeify_customer" "acme" { provider = uptimeify.acme name = "ACME GmbH" } resource "uptimeify_website" "acme_shop" { provider = uptimeify.acme customer_id = tonumber(data.uptimeify_customer.acme.id) name = "ACME shop" url = "https://shop.acme.example/" } ``` With Terragrunt, generate the `provider` block and pass the token per unit, as with any other provider. ## What a customer token can do A customer token manages the monitors of its customers; monitors it creates are always `self_service`. It cannot create customers. On an organization-wide resource the API answers `403 customerScopedTokenForbidden`; a token that lacks a scope gets `403 apiTokenScopeForbidden` with the missing scope in `data.requiredScope`. Which endpoint needs which scope: [Permissions by endpoint](/api/introduction/permissions-by-endpoint). Resources that can be scoped either way, such as [`uptimeify_tag`](/terraform/resources/tag), must set `customer_id` when you use a customer token. ### uptimeify_custom_field URL: https://docs.uptimeify.io/terraform/data-sources/custom_field Description: Look up one active custom field by id or by field_key (exactly one). Summary: Look up one active custom field by `id` or by `field_key` (exactly one). ## Example Usage ```terraform data "uptimeify_custom_field" "contract" { field_key = "contract" } ``` ## Schema ### Optional - `field_key` (String) - `id` (String) Numeric field id. ### Read-Only - `created_at` (String) - `display_order` (Number) - `field_type` (String) `text`, `number`, `email`, `url`, `select`. Default `text`. - `help_text` (String) - `is_required` (Boolean) - `name` (String) - `options` (List of String) Choices of a `select` field, at most 50 of up to 100 characters. - `organization_id` (Number) - `placeholder` (String) - `show_in_table` (Boolean) Show as a column in the customer list. - `updated_at` (String) ### uptimeify_customer URL: https://docs.uptimeify.io/terraform/data-sources/customer Description: Look up one customer by id or by name (exactly one). Fails when no or several visible customers carry the name. Summary: Look up one customer by `id` or by `name` (exactly one). Fails when no or several visible customers carry the name. ## Example Usage ```terraform data "uptimeify_customer" "shop" { name = "Example Shop GmbH" } data "uptimeify_customer" "by_id" { id = "12" } ``` ## Schema ### Optional - `id` (String) Numeric id or public id. Use `tonumber(id)` for `customer_id` arguments. - `name` (String) ### Read-Only - `public_id` (String) - `status` (String) `active` or `inactive`. ### uptimeify_dns_monitor URL: https://docs.uptimeify.io/terraform/data-sources/dns_monitor Description: Look up one DNS monitor by numeric id or public id. Secrets are never readable. Summary: Look up one DNS monitor by numeric id or public id. Secrets are never readable. ## Example Usage ```terraform data "uptimeify_dns_monitor" "this" { id = "42" } ``` ## Schema ### Required - `id` (String) Numeric id or public id. ### Read-Only - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `created_at` (String) - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `expected_values` (Map of List of String) Expected answers per record type (upper-case key); every type in `record_types` needs at least one value. Values unique and without surrounding spaces. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `match_mode` (String) `exact` (answer set equals the expected values) or `contains` (answer includes them). - `name` (String) Display name, 1 to 255 characters. - `organization_id` (Number) - `public_id` (String) Public UUID of the DNS monitor. - `record_types` (List of String) Record types to resolve, upper case and unique, e.g. `["A", "MX"]`. - `require_expected_values` (Boolean) Defaults to false. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. - `trigger_on_mismatch` (Boolean) Alert when the answers do not match. Defaults to true. - `trigger_on_resolve_error` (Boolean) Alert when the name does not resolve. Defaults to true. - `updated_at` (String) ### uptimeify_ftp_monitor URL: https://docs.uptimeify.io/terraform/data-sources/ftp_monitor Description: Look up one FTP monitor by numeric id or public id. Secrets are never readable. Summary: Look up one FTP monitor by numeric id or public id. Secrets are never readable. ## Example Usage ```terraform data "uptimeify_ftp_monitor" "this" { id = "42" } ``` ## Schema ### Required - `id` (String) Numeric id or public id. ### Read-Only - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `check_mode` (String) `protocol` (full login check, credentials required) or `tcp` (port reachability only; the API then stores no protocol settings and no credentials). Defaults to `protocol`. - `created_at` (String) - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `name` (String) Display name, 1 to 255 characters. - `organization_id` (Number) - `port` (Number) TCP port. Unset = 990 with tls_mode `implicit`, else 21. - `public_id` (String) Public UUID of the FTP monitor. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. - `tls_mode` (String) `none` (plain FTP), `explicit` (AUTH TLS) or `implicit` (FTPS). Defaults to `none`. - `updated_at` (String) - `user` (String) Login user. Required in check_mode `protocol`. ### uptimeify_icmp_monitor URL: https://docs.uptimeify.io/terraform/data-sources/icmp_monitor Description: Look up one ICMP monitor by numeric id or public id. Secrets are never readable. Summary: Look up one ICMP monitor by numeric id or public id. Secrets are never readable. ## Example Usage ```terraform data "uptimeify_icmp_monitor" "this" { id = "42" } ``` ## Schema ### Required - `id` (String) Numeric id or public id. ### Read-Only - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `created_at` (String) - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `name` (String) Display name, 1 to 255 characters. - `organization_id` (Number) - `packet_size` (Number) Payload size in bytes, 1 to 65507. Unset = worker default. - `ping_count` (Number) Echo requests per check, 1 to 10. Unset = worker default. - `public_id` (String) Public UUID of the ICMP monitor. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. - `updated_at` (String) ### uptimeify_im_alert_source URL: https://docs.uptimeify.io/terraform/data-sources/im_alert_source Description: Look up one Incident Management alert source by id or by name (exactly one). Fails when no or several sources match the name. Tokens and secrets are never returned. Summary: Look up one Incident Management alert source by `id` or by `name` (exactly one). Fails when no or several sources match the name. Tokens and secrets are never returned. ## Example Usage ```terraform data "uptimeify_im_alert_source" "zabbix" { name = "Zabbix" } output "zabbix_title_selector" { value = data.uptimeify_im_alert_source.zabbix.payload_mapping.title } ``` ## Schema ### Optional - `id` (String) Numeric source id. - `name` (String) ### Read-Only - `auto_resolve` (Boolean) Resolve the incident when the vendor sends a resolve. Default `true`. - `bearer_enabled` (Boolean) Require `Authorization: Bearer `. Enabling it the first time mints the token. - `created_at` (String) - `grouping_window_minutes` (Number) Group alerts arriving within this many minutes into one incident. Unset = group by dedup key only. - `hmac_enabled` (Boolean) Require an HMAC signature. Enabling needs a secret: set `hmac_secret_wo` (once is enough, disabling keeps the secret stored). - `maintenance_windows` (Attributes List) Recurring windows in which alerts are stored as suppressed instead of opening incidents. At most 20. (see [below for nested schema](#nested-schema-for-maintenance_windows)) - `organization_id` (Number) - `payload_mapping` (Attributes) How a vendor payload becomes an alert. Either the v2 `attributes` list or the v1 selector fields (`title`, `severity`, `status`, ...). Unset = not managed: the server keeps its mapping (a preset type starts with the preset mapping; read it with the data source); removing the block later keeps the last mapping. An import reads the stored mapping. Must stay unset for `type = "email"` (the server builds that mapping). (see [below for nested schema](#nested-schema-for-payload_mapping)) - `secondary_expires_at` (String) End of the grace period of the previous ingest token after a rotation. - `team_id` (Number) Team that owns incidents from this source. - `type` (String) A preset name from `GET /api/im/sources/presets` (e.g. `zabbix`, `datadog`, `grafana`, `alertmanager`, `sentry`, `beszel`, `custom`), `api` (no webhook URL, fed by `POST /api/im/events`) or `email`. Changing it replaces the source. - `updated_at` (String) - `url_token_enabled` (Boolean) `authMode.urlToken`. The server stores the flag; unset = not sent. ### Nested Schema for `maintenance_windows` Read-Only: - `days_of_week` (List of Number) ISO weekdays, 1 = Monday to 7 = Sunday. Unset = every day. - `from` (String) `HH:MM`, 24 h. - `timezone` (String) IANA zone. Unset = the organization zone. - `to` (String) `HH:MM`, 24 h. ### Nested Schema for `payload_mapping` Read-Only: - `attributes` (Attributes List) v2 attribute-list mapping: ordered attributes, each with a step chain. (see [below for nested schema](#nested-schema-for-payload_mappingattributes)) - `custom` (Map of String) v1: extra field -> selector. - `dedup_key` (String) v1: selector of the dedup key. - `default_severity` (String) Severity when the mapping yields none. The server treats unset as `sev3`. - `email_selectors` (Map of String) email sources: field -> email selector. The server builds it on create; read here. - `host` (String) v1: selector of the host. - `resolve_values` (List of String) v1: status values that resolve the alert. - `severity` (String) v1: selector of the vendor severity. - `severity_map` (Map of String) v1: vendor value -> `sev1`..`sev4`. - `status` (String) v1: selector of the vendor status. - `title` (String) v1: selector of the alert title. - `url` (String) v1: selector of the URL. ### Nested Schema for `payload_mapping.attributes` Read-Only: - `flags` (Attributes) (see [below for nested schema](#nested-schema-for-payload_mappingattributesflags)) - `key` (String) - `standard` (Boolean) A standard alert field (title, severity, status, ...). - `steps` (Attributes List) (see [below for nested schema](#nested-schema-for-payload_mappingattributessteps)) ### Nested Schema for `payload_mapping.attributes.flags` Read-Only: - `expand` (Boolean) -… ### uptimeify_im_channel URL: https://docs.uptimeify.io/terraform/data-sources/im_channel Description: Look up one Incident Management paging channel by id or by name (exactly one). Fails when no or several channels match the name. Secrets are never returned. Summary: Look up one Incident Management paging channel by `id` or by `name` (exactly one). Fails when no or several channels match the name. Secrets are never returned. ## Example Usage ```terraform data "uptimeify_im_channel" "ops" { name = "Ops Slack" } output "ops_channel_id" { value = data.uptimeify_im_channel.ops.id } ``` ## Schema ### Optional - `id` (String) Numeric channel id. - `name` (String) ### Read-Only - `created_at` (String) - `email` (String) `type = "email"`: recipient address (required there). - `has_webhook_url` (Boolean) Whether a webhook URL is stored. - `header_names` (List of String) Names of the stored headers, sorted (values are never returned). - `is_active` (Boolean) Default `true`. The organization fallback channel cannot be deactivated. - `organization_id` (Number) - `team_id` (Number) Team of the organization; unset = organization-wide channel. - `type` (String) `webhook`, `slack` or `email`. - `updated_at` (String) ### uptimeify_im_on_call URL: https://docs.uptimeify.io/terraform/data-sources/im_on_call Description: Who is on call right now (read at plan time, so it changes between runs). Incident Management must be active for the organization. Summary: Who is on call right now (read at plan time, so it changes between runs). Incident Management must be active for the organization. ## Example Usage ```terraform # Who holds the pager of team 7 right now, per escalation tier. data "uptimeify_im_on_call" "platform" { team_id = 7 } output "first_tier_on_call" { value = [for u in data.uptimeify_im_on_call.platform.tiers[0].users : u.user_name] } ``` ## Schema ### Optional - `schedule_id` (Number) Only this schedule. - `team_id` (Number) Only this team; also fills `tiers`. ### Read-Only - `entries` (Attributes List) One entry per schedule with someone on call now (`GET /api/im/on-call`), after the filters. (see [below for nested schema](#nested-schema-for-entries)) - `tiers` (Attributes List) With `team_id`: one entry per escalation tier of the team with everyone on call now (`GET /api/im/teams/{id}/on-call-now`), overrides applied. Null without `team_id`. (see [below for nested schema](#nested-schema-for-tiers)) ### Nested Schema for `entries` Read-Only: - `schedule_id` (Number) - `shift_ends_at` (String) End of the current shift (RFC 3339). - `team_id` (Number) - `user_id` (String) User id. - `user_image` (String) Avatar URL, may be null. - `user_name` (String) Display name, may be null. ### Nested Schema for `tiers` Read-Only: - `tier_id` (Number) - `tier_order` (Number) - `uncovered_since` (String) Since when nobody covers the tier; null when covered or not within 14 days. - `users` (Attributes List) (see [below for nested schema](#nested-schema-for-tiersusers)) ### Nested Schema for `tiers.users` Read-Only: - `user_id` (String) User id. - `user_image` (String) Avatar URL, may be null. - `user_name` (String) Display name, may be null. ### uptimeify_im_outbound_integration URL: https://docs.uptimeify.io/terraform/data-sources/im_outbound_integration Description: Look up one Incident Management outbound integration by id or by name (exactly one). Fails when no or several integrations match the name. Secrets are never returned. Summary: Look up one Incident Management outbound integration by `id` or by `name` (exactly one). Fails when no or several integrations match the name. Secrets are never returned. ## Example Usage ```terraform data "uptimeify_im_outbound_integration" "jira" { name = "Jira OPS" } output "jira_project" { value = data.uptimeify_im_outbound_integration.jira.project_key } ``` ## Schema ### Optional - `id` (String) Numeric integration id. - `name` (String) ### Read-Only - `base_url` (String) `jira`: site URL, https only, required. - `created_at` (String) - `email` (String) `jira`: account email, required. - `event_kinds` (List of String) Events to forward: `incident_created`, `acknowledged`, `severity_changed`, `status_changed`, `comment`, `resolved`. Unset = all, except `jira`, where the server stores `["incident_created"]`. Removing it from the configuration keeps the stored list. - `filter_severities` (List of String) Only these severities, `sev1` to `sev4`. Unset = all. - `filter_team_ids` (List of Number) Only incidents of these teams (of the organization). Unset = all. - `has_api_key` (Boolean) Whether an Opsgenie API key is stored. - `has_api_token` (Boolean) Whether a Jira API token is stored. - `has_bearer_token` (Boolean) Whether a bearer token is stored. - `has_headers` (Boolean) Whether custom headers are stored. - `has_routing_key` (Boolean) Whether a PagerDuty routing key is stored. - `has_webhook_url` (Boolean) Whether a webhook URL is stored. - `is_active` (Boolean) Default `true`. - `organization_id` (Number) - `project_key` (String) `jira`: project key, required. - `team_id` (Number) Owning team; unset = organization-wide (needs an org admin). - `type` (String) `slack`, `teams`, `discord`, `jira`, `pagerduty_v2`, `opsgenie` or `webhook`. Changing it replaces the integration. - `updated_at` (String) ### uptimeify_im_routing_rule URL: https://docs.uptimeify.io/terraform/data-sources/im_routing_rule Description: Read one Incident Management routing rule by id. Summary: Read one Incident Management routing rule by id. ## Example Usage ```terraform data "uptimeify_im_routing_rule" "db" { id = "17" } ``` ## Schema ### Required - `id` (String) Numeric rule id. ### Read-Only - `created_at` (String) - `match` (Attributes) What the rule matches; all set fields must match. Unset or `{}` = catch-all. All ids must belong to the organization. (see [below for nested schema](#nested-schema-for-match)) - `organization_id` (Number) - `priority` (Number) Lower runs first. Default `100`. - `severity_override` (String) Unset = keep the mapped severity. - `team_id` (Number) The team that receives matching incidents. - `updated_at` (String) ### Nested Schema for `match` Read-Only: - `customer_ids` (List of Number) Customer ids. At most 500. - `field_matches` (Map of String) Payload field -> expected value, at most 50 entries. - `monitor_ids` (List of Number) Ids of any monitor type (website, DNS, ICMP, ...). At most 500. - `severity` (List of String) `sev1` to `sev4`. - `source_ids` (List of Number) Alert source ids. At most 500. - `tags` (List of String) Alert tags. At most 200. ### uptimeify_im_schedule URL: https://docs.uptimeify.io/terraform/data-sources/im_schedule Description: Look up one on-call schedule by id or by name (exactly one). The default schedules of different teams can share a name (Tier 1 schedule), so team_id narrows a lookup by name. Fails when no or several schedules match. Summary: Look up one on-call schedule by `id` or by `name` (exactly one). The default schedules of different teams can share a name (`Tier 1 schedule`), so `team_id` narrows a lookup by name. Fails when no or several schedules match. ## Example Usage ```terraform data "uptimeify_im_team" "platform" { name = "Platform" } # Default schedules of different teams can share a name, team_id narrows the lookup. data "uptimeify_im_schedule" "first_tier" { name = "Tier 1 schedule" team_id = tonumber(data.uptimeify_im_team.platform.id) } # Take the first member of the looked-up schedule off call for the holidays. resource "uptimeify_im_schedule_override" "holiday" { schedule_id = data.uptimeify_im_schedule.first_tier.id user_id = data.uptimeify_im_schedule.first_tier.rotations[0].members[0] type = "offline" starts_at = "2030-08-01T00:00:00Z" ends_at = "2030-08-15T00:00:00Z" } ``` ## Schema ### Optional - `id` (String) Numeric schedule id. - `name` (String) - `team_id` (Number) Team of the schedule; narrows a lookup by `name`, conflicts with `id`. ### Read-Only - `auto_rotation_size` (Number) - `created_at` (String) - `custom_repeat_unit` (String) - `custom_repeat_value` (Number) - `effective_from` (String) - `effective_until` (String) - `organization_id` (Number) - `rotation_mode` (String) - `rotation_repeats` (String) - `rotations` (Attributes List) Ordered rotation groups. (see [below for nested schema](#nested-schema-for-rotations)) - `round_robin_size` (Number) - `starts_on_date_of_month` (Number) - `starts_on_day_of_week` (Number) - `starts_on_time` (String) - `team_name` (String) - `tier_id` (Number) - `timezone` (String) - `updated_at` (String) - `weekly_schedules` (Attributes List) Weekly windows; empty = around the clock. (see [below for nested schema](#nested-schema-for-weekly_schedules)) ### Nested Schema for `rotations` Read-Only: - `members` (List of String) User ids in order. ### Nested Schema for `weekly_schedules` Read-Only: - `days` (List of Number) ISO weekdays, 1 = Monday to 7 = Sunday. - `from` (String) - `until` (String) ### uptimeify_im_statuspage_rule URL: https://docs.uptimeify.io/terraform/data-sources/im_statuspage_rule Description: Look up one Incident Management status page rule by numeric id. Summary: Look up one Incident Management status page rule by numeric id. ## Example Usage ```terraform data "uptimeify_im_statuspage_rule" "acme" { id = "17" } ``` ## Schema ### Required - `id` (String) Numeric rule id. ### Read-Only - `auto_resolve` (Boolean) - `created_at` (String) - `message` (String) - `min_severity` (String) - `organization_id` (Number) - `status_page_id` (Number) - `target_state` (String) - `team_id` (Number) - `updated_at` (String) ### uptimeify_im_team URL: https://docs.uptimeify.io/terraform/data-sources/im_team Description: Look up one Incident Management team by id or by name (exactly one). Fails when no or several teams match the name. Summary: Look up one Incident Management team by `id` or by `name` (exactly one). Fails when no or several teams match the name. ## Example Usage ```terraform data "uptimeify_im_team" "platform" { name = "Platform" } ``` ## Schema ### Optional - `id` (String) Numeric team id. - `name` (String) ### Read-Only - `analytics_enabled` (Boolean) - `created_at` (String) - `engagement_report_day_of_week` (Number) - `engagement_report_enabled` (Boolean) - `engagement_report_time` (String) - `escalation_repeats` (Number) - `escalation_repeats_after_minutes` (Number) - `escalation_repeats_stop_mode` (String) - `label_color` (String) - `organization_id` (Number) - `timezone` (String) ### uptimeify_imap_pop_monitor URL: https://docs.uptimeify.io/terraform/data-sources/imap_pop_monitor Description: Look up one IMAP/POP3 monitor by numeric id or public id. Secrets are never readable. Summary: Look up one IMAP/POP3 monitor by numeric id or public id. Secrets are never readable. ## Example Usage ```terraform data "uptimeify_imap_pop_monitor" "this" { id = "42" } ``` ## Schema ### Required - `id` (String) Numeric id or public id. ### Read-Only - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `check_mode` (String) `protocol` (full login check, credentials required) or `tcp` (port reachability only; the API then stores no protocol settings and no credentials). Defaults to `protocol`. - `created_at` (String) - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `name` (String) Display name, 1 to 255 characters. - `organization_id` (Number) - `port` (Number) TCP port. Unset = 993/143 for IMAP, 995/110 for POP3 (with/without `tls`); required in check_mode `tcp`. - `protocol` (String) `imap` or `pop3`. Defaults to `imap`. - `public_id` (String) Public UUID of the IMAP/POP3 monitor. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. - `tls` (Boolean) Implicit TLS (IMAPS/POP3S). Defaults to false. - `tls_reject_unauthorized` (Boolean) Reject invalid server certificates. Defaults to true. - `updated_at` (String) - `user` (String) Login user. Required in check_mode `protocol`. ### uptimeify_maintenance_window URL: https://docs.uptimeify.io/terraform/data-sources/maintenance_window Description: Look up one maintenance window by id. Summary: Look up one maintenance window by `id`. ## Example Usage ```terraform data "uptimeify_maintenance_window" "patch_night" { id = "42" } ``` ## Schema ### Required - `id` (String) Numeric id or public id. ### Read-Only - `created_at` (String) - `customer_id` (Number) Set only for a whole-customer window (no targets, no tags). - `description` (String) - `end_time` (String) UTC, RFC3339. - `is_active` (Boolean) - `name` (String) - `public_id` (String) - `recurrence_pattern` (Attributes) (see [below for nested schema](#nested-schema-for-recurrence_pattern)) - `start_time` (String) UTC, RFC3339. - `tag_ids` (Set of Number) - `targets` (Attributes Set) (see [below for nested schema](#nested-schema-for-targets)) - `timezone` (String) IANA zone the recurrence is read in. - `updated_at` (String) ### Nested Schema for `recurrence_pattern` Read-Only: - `day_of_month` (Number) - `days_of_week` (List of Number) - `end_recurrence_date` (String) - `frequency` (String) - `interval_count` (Number) ### Nested Schema for `targets` Read-Only: - `id` (Number) - `type` (String) ### uptimeify_monitoring_locations URL: https://docs.uptimeify.io/terraform/data-sources/monitoring_locations Description: Countries with at least one active check worker. Use country_codes for allowed_check_country_codes. Summary: Countries with at least one active check worker. Use `country_codes` for `allowed_check_country_codes`. ## Example Usage ```terraform data "uptimeify_monitoring_locations" "all" {} output "check_countries" { value = data.uptimeify_monitoring_locations.all.country_codes } ``` ## Schema ### Read-Only - `countries` (Attributes List) Per country, sorted by code. (see [below for nested schema](#nested-schema-for-countries)) - `country_codes` (List of String) ISO 3166-1 alpha-2 codes, sorted. - `id` (String) Always `monitoring-locations`. ### Nested Schema for `countries` Read-Only: - `code` (String) ISO 3166-1 alpha-2. - `locations` (Number) Check locations in the country. - `workers` (Number) Active check workers in the country. ### uptimeify_notification_channel URL: https://docs.uptimeify.io/terraform/data-sources/notification_channel Description: Look up one notification channel by id or by name (exactly one). Fails when no or several channels carry the name. Secrets are never returned (see secrets_set). Website overrides are not found by name. Summary: Look up one notification channel by `id` or by `name` (exactly one). Fails when no or several channels carry the name. Secrets are never returned (see `secrets_set`). Website overrides are not found by name. ## Example Usage ```terraform data "uptimeify_notification_channel" "ops" { name = "Ops mail" } data "uptimeify_notification_channel" "by_id" { id = "42" } ``` ## Schema ### Optional - `customer_id` (Number) With `name`: search this customer's channels too (default: organization channels only). - `id` (String) Numeric channel id. - `name` (String) ### Read-Only - `allowed_package_types` (Set of String) - `category` (String) `direct` (default) or `integration`. - `conditions` (String) Delivery conditions as a JSON object. Unset = always. - `config` (String) Provider settings without secrets, as a JSON object (`jsonencode({ email = "ops@example.com" })`). Keys removed here are cleared. - `created_at` (String) - `delay_seconds` (Number) Wait before sending, 0 to 86400 seconds. - `is_active` (Boolean) - `organization_id` (Number) - `secrets_set` (Map of Boolean) Which secrets are stored, e.g. `{ Secret = true }` (the API's `has` flags). - `type` (String) Channel type: `email`, `sms`, `webhook`, `incident_management`, `slack`, `discord`, `teams`, `pagerduty`, `pushover`, `opsgenie`, `matrix`, `jira`, `allquiet`, `telegram`, `googlechat`, `mattermost`, `rocketchat`, `ntfy`, `gotify`, `ilert`, `grafanaoncall`, `incidentio`, `squadcast`, `github`, `gitlab`, `linear`, `servicenow`, `lark`, `dingtalk`, `wecom`. ### uptimeify_organization URL: https://docs.uptimeify.io/terraform/data-sources/organization Description: The token's own organization (GET /api/organization). Billing, address, quota and MFA fields are only filled for admin tokens. Summary: The token's own organization (`GET /api/organization`). Billing, address, quota and MFA fields are only filled for admin tokens. ## Example Usage ```terraform data "uptimeify_organization" "this" {} output "organization_name" { value = data.uptimeify_organization.this.name } ``` ## Schema ### Read-Only - `billing_cycle` (String) - `billing_email` (String) - `city` (String) - `company_name` (String) - `country` (String) - `default_notification_channels` (Attributes) (see [below for nested schema](#nested-schema-for-default_notification_channels)) - `default_notification_targets` (Attributes) (see [below for nested schema](#nested-schema-for-default_notification_targets)) - `deletion_due_at` (String) - `email_language` (String) - `id` (Number) The ID of this resource. - `name` (String) - `payment_method` (String) - `postal_code` (String) - `public_id` (String) - `quota_auto_upgrade_enabled` (Boolean) - `quota_extra_sms_price_cents` (Number) - `quota_ips_limit` (Number) - `quota_monthly_price_cents` (Number) - `quota_sms_included` (Number) - `quota_websites_limit` (Number) - `require_mfa_admins` (Boolean) - `require_mfa_customers` (Boolean) - `require_mfa_editors` (Boolean) - `require_mfa_readonly` (Boolean) - `sms_overage_safety_cap_cents_monthly` (Number) - `status` (String) - `street` (String) - `vat_id` (String) ### Nested Schema for `default_notification_channels` Read-Only: - `email` (Boolean) - `integrations` (Boolean) - `sms` (Boolean) - `webhook` (Boolean) ### Nested Schema for `default_notification_targets` Read-Only: - `email` (String) - `integrations` (String) - `sms` (String) - `webhook` (String) ### uptimeify_package_configs URL: https://docs.uptimeify.io/terraform/data-sources/package_configs Description: The organization's package configurations (GET /api/package-configs): limits, checks and alert defaults per package type, e.g. to look up the package_type of a customer. Summary: The organization's package configurations (`GET /api/package-configs`): limits, checks and alert defaults per package type, e.g. to look up the `package_type` of a customer. ## Example Usage ```terraform data "uptimeify_package_configs" "all" {} output "package_types" { value = [for p in data.uptimeify_package_configs.all.package_configs : p.package_type] } ``` ## Schema ### Read-Only - `package_configs` (Attributes List) (see [below for nested schema](#nested-schema-for-package_configs)) ### Nested Schema for `package_configs` Read-Only: - `alert_consecutive_checks` (Number) - `alert_location_threshold` (String) - `alert_location_threshold_count` (Number) - `alert_reminder_interval` (Number) - `alert_repeat_interval_minutes` (Number) - `allow_self_service` (Boolean) - `allowed_check_country_codes` (List of String) - `check_interval_minutes` (Number) - `check_locations` (Number) - `data_retention_months` (Number) - `display_name` (String) - `dnsbl_reminder_interval` (Number) - `enable_email_alerts` (Boolean) - `enable_https_check` (Boolean) - `enable_integration_alerts` (Boolean) - `enable_keyword_check` (Boolean) - `enable_maintenance_windows` (Boolean) - `enable_pdf_reports` (Boolean) - `enable_post_request_escalation` (Boolean) - `enable_response_time_check` (Boolean) - `enable_size_check` (Boolean) - `enable_sms_alerts` (Boolean) - `enable_ssl_check` (Boolean) - `enable_status_check` (Boolean) - `enable_webhook_alerts` (Boolean) - `flapping_enabled` (Boolean) - `flapping_incident_count` (Number) - `flapping_recovery_clean_cycles` (Number) - `flapping_window_minutes` (Number) - `id` (Number) - `max_self_service_urls` (Number) - `max_status_pages` (Number) - `max_urls` (Number) - `monthly_reports_default` (Boolean) - `notes` (String) - `notification_delay_minutes` (Number) - `package_type` (String) - `reminder_delay_minutes` (Number) - `ssl_expiry_reminder_interval` (Number) - `used_by_customer_count` (Number) ### uptimeify_smtp_monitor URL: https://docs.uptimeify.io/terraform/data-sources/smtp_monitor Description: Look up one SMTP monitor by numeric id or public id. Secrets are never readable. Summary: Look up one SMTP monitor by numeric id or public id. Secrets are never readable. ## Example Usage ```terraform data "uptimeify_smtp_monitor" "this" { id = "42" } ``` ## Schema ### Required - `id` (String) Numeric id or public id. ### Read-Only - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `auth_user` (String) SMTP user. Required in check_mode `protocol`. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `check_mode` (String) `protocol` (full login check, credentials required) or `tcp` (port reachability only; the API then stores no protocol settings and no credentials). Defaults to `protocol`. - `created_at` (String) - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `ignore_tls` (Boolean) Do not upgrade with STARTTLS. Defaults to false. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `name` (String) Display name, 1 to 255 characters. - `organization_id` (Number) - `port` (Number) TCP port. Unset = 465 with `secure`, else 25. - `public_id` (String) Public UUID of the SMTP monitor. - `require_tls` (Boolean) Fail without STARTTLS. Defaults to false. - `secure` (Boolean) Implicit TLS (SMTPS). Defaults to false. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. - `updated_at` (String) ### uptimeify_ssh_monitor URL: https://docs.uptimeify.io/terraform/data-sources/ssh_monitor Description: Look up one SSH monitor by numeric id or public id. Secrets are never readable. Summary: Look up one SSH monitor by numeric id or public id. Secrets are never readable. ## Example Usage ```terraform data "uptimeify_ssh_monitor" "this" { id = "42" } ``` ## Schema ### Required - `id` (String) Numeric id or public id. ### Read-Only - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `check_mode` (String) `protocol` (full login check, credentials required) or `tcp` (port reachability only; the API then stores no protocol settings and no credentials). Defaults to `protocol`. - `created_at` (String) - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `name` (String) Display name, 1 to 255 characters. - `organization_id` (Number) - `port` (Number) TCP port. Unset = 22. - `public_id` (String) Public UUID of the SSH monitor. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. - `updated_at` (String) - `username` (String) Login user. Required in check_mode `protocol`. ### uptimeify_status_page URL: https://docs.uptimeify.io/terraform/data-sources/status_page Description: Look up one status page by id, slug or name (exactly one). Fails when no or several visible pages carry the name. Summary: Look up one status page by `id`, `slug` or `name` (exactly one). Fails when no or several visible pages carry the name. ## Example Usage ```terraform data "uptimeify_status_page" "by_slug" { slug = "acme" } data "uptimeify_status_page" "by_id" { id = "42" } ``` ## Schema ### Optional - `id` (String) Numeric id or public id. - `name` (String) - `slug` (String) ### Read-Only - `access_password_set_at` (String) - `created_at` (String) - `customer_id` (Number) - `customer_name` (String) - `description` (String) - `has_password` (Boolean) - `hidden_monitors` (Attributes Set) Monitors of the customer the page does not show. (see [below for nested schema](#nested-schema-for-hidden_monitors)) - `include_customer_monitors` (Boolean) Every monitor of the customer appears after the components. - `ip_allowlist` (Set of String) CIDR ranges allowed to see the page; empty = no IP restriction. - `is_published` (Boolean) - `management_type` (String) `managed` or `self_service`. - `monitor_updates_enabled` (Boolean) Monitors write to the page (state, incidents, subscriber notifications); `false` = only manual reports and explicitly linked incidents. - `organization_id` (Number) - `public_id` (String) - `push_subscriptions_enabled` (Boolean) - `sms_subscriptions_enabled` (Boolean) - `subscription_delay_minutes` (Number) - `subscriptions_enabled` (Boolean) - `updated_at` (String) - `visibility` (String) `public`, `customer_members_only`, `password_protected` or `sso_members_only`. ### Nested Schema for `hidden_monitors` Read-Only: - `id` (Number) - `type` (String) ### uptimeify_tag URL: https://docs.uptimeify.io/terraform/data-sources/tag Description: Look up one tag by id or by name (exactly one). Fails when no or several visible tags match the name. Summary: Look up one tag by `id` or by `name` (exactly one). Fails when no or several visible tags match the name. ## Example Usage ```terraform data "uptimeify_tag" "production" { name = "production" } data "uptimeify_tag" "by_id" { id = "42" } ``` ## Schema ### Optional - `id` (String) Numeric id or public id. - `name` (String) ### Read-Only - `color` (String) - `created_at` (String) - `customer_id` (Number) - `public_id` (String) - `updated_at` (String) ### uptimeify_tcp_monitor URL: https://docs.uptimeify.io/terraform/data-sources/tcp_monitor Description: Look up one TCP monitor by numeric id or public id. Secrets are never readable. Summary: Look up one TCP monitor by numeric id or public id. Secrets are never readable. ## Example Usage ```terraform data "uptimeify_tcp_monitor" "this" { id = "42" } ``` ## Schema ### Required - `id` (String) Numeric id or public id. ### Read-Only - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `created_at` (String) - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `expect_banner` (String) Text the server's greeting must contain, at most 255 characters. - `expected_state` (String) `up` (default) alerts when the port is not reachable. `down` inverts the monitor: an open connection is an outage; refused, timeout, reset and unreachable count as OK. A DNS failure stays an outage. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `name` (String) Display name, 1 to 255 characters. - `organization_id` (Number) - `port` (Number) - `public_id` (String) Public UUID of the TCP monitor. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. - `updated_at` (String) ### uptimeify_user URL: https://docs.uptimeify.io/terraform/data-sources/user Description: Look up one login of the organization by email (case-insensitive), e.g. for team members and rotations. Summary: Look up one login of the organization by email (case-insensitive), e.g. for team members and rotations. ## Example Usage ```terraform data "uptimeify_user" "alice" { email = "alice@example.com" } ``` ## Schema ### Required - `email` (String) ### Read-Only - `id` (String) User id, as `user_id` in IM resources. - `is_active` (Boolean) - `language` (String) `de`, `en` or `da`; null = organization language. - `name` (String) - `role` (String) `admin`, `editor`, `readonly` or `responder`. IM accepts admin, editor and responder. ### uptimeify_website URL: https://docs.uptimeify.io/terraform/data-sources/website Description: Read one website monitor by id. Secrets (headers, body, auth secrets) are never returned. Summary: Read one website monitor by id. Secrets (headers, body, auth secrets) are never returned. ## Example Usage ```terraform data "uptimeify_website" "api" { id = "42" } ``` ## Schema ### Required - `id` (String) Numeric id or public id. ### Read-Only - `allowed_check_country_codes` (Set of String) Upper-case ISO country codes of the check locations. Unset at create: the package default (null = all). Removing it later keeps the last value. - `auth_mode` (String) `none`, `authorization_header` (needs `authorization_header_wo`) or `basic` (needs `basic_auth_username` and `basic_auth_password_wo`). Defaults to `none`. - `basic_auth_username` (String) Username for `auth_mode = "basic"`. - `check_domain_expiry_enabled` (Boolean) Domain expiry check. Unset: the package default. The package may switch it off; a full update switches it off on heartbeat monitors. - `check_expected_response_enabled` (Boolean) Compare the response body with `expected_response_value`. Defaults to `false`. - `check_https_redirect_enabled` (Boolean) HTTP to HTTPS redirect check. Unset: the package default. The package may switch it off; a full update switches it off on heartbeat monitors. - `check_interval` (Number) Minutes between checks; at least the package minimum, at most 1440 (43200 for heartbeat). Defaults to `30`. - `check_keyword_enabled` (Boolean) Keyword check against `search_term`; off without a search term. Unset: the package default. The package may switch it off; a full update switches it off on heartbeat monitors. - `check_response_time_enabled` (Boolean) Response time check (the threshold is not configurable per monitor). Unset: the package default. The package may switch it off; a full update switches it off on heartbeat monitors. - `check_size_enabled` (Boolean) Page size check against `min_page_size`/`max_page_size`; off without a limit. Unset: the package default. The package may switch it off; a full update switches it off on heartbeat monitors. - `check_ssl_enabled` (Boolean) Certificate validity and expiry check. Unset: the package default. The package may switch it off; a full update switches it off on heartbeat monitors. - `check_status_enabled` (Boolean) Status code check against `expected_status_codes`. Unset: the package default. The package may switch it off; a full update switches it off on heartbeat monitors. - `connect_host` (String) Connect target (`connectHost`): IP or host name to connect to instead of the URL's host; SNI and Host header stay the URL's. Lower case, without port (use `connect_port`), must be public. - `connect_port` (Number) Port of the connect target; unset = the URL's port. - `connect_tls_insecure` (Boolean) Skip certificate verification at the connect target; needs `connect_host`. Defaults to `false`. - `cookie_handling` (String) `none` or `jar` (keep cookies across redirects). Defaults to `none`. - `created_at` (String) - `customer_id` (Number) Numeric id of the customer that owns the monitor. Changing it moves the monitor. - `domain_expiry_error_days` (Number) Error this many days before domain expiry. Defaults to `7`. - `domain_expiry_notice_days` (Number) Warn this many days before domain expiry. Defaults to `30`. - `expected_response_json_path` (String) - `expected_response_match_type` (String) `contains`, `equals` or `json_path_equals` (needs `expected_response_json_path`). Defaults to `contains`. - `expected_response_value` (String) - `expected_state` (String) Heartbeat monitors only: `up` alerts when pings stop; `down` inverts the monitor, a ping is an outage and silence beyond the interval plus `heartbeat_grace_period_minutes` counts as OK. Other types accept only `up` (the API answers 400 `expectedStateNotSupported`). Defaults to `up`. - `expected_status_codes` (String) Comma-separated accepted status codes. Defaults to `200,301,302`. - `follow_redirects` (Boolean) Defaults to `true`. - `has_custom_headers` (Boolean) Whether custom headers are stored. - `has_request_body` (Boolean) Whether a reques… ### Getting started URL: https://docs.uptimeify.io/terraform/getting-started Description: Install the Uptimeify provider, authenticate with an API token and create your first website monitor with OpenTofu or Terraform. Summary: ## 1. Create an API token Open **Settings > API** in the dashboard and create a token, see [Generate an API token](/api/introduction/generate-api-token). An organization token manages everything in the organization; a [customer token](/terraform/customer-tokens) only its customers. ```sh ``` ## 2. Write the configuration ```terraform terraform { required_version = ">= 1.11" required_providers { uptimeify = { source = "uptimeify/uptimeify" version = "~> 0.5" } } } provider "uptimeify" {} # reads UPTIMEIFY_API_TOKEN data "uptimeify_customer" "shop" { name = "Example Shop GmbH" } resource "uptimeify_website" "shop" { customer_id = tonumber(data.uptimeify_customer.shop.id) name = "Shop homepage" url = "https://shop.example.com/" check_interval = 5 check_expected_response_enabled = true expected_response_match_type = "contains" expected_response_value = "Add to cart" } resource "uptimeify_tag" "production" { name = "production" color = "red" } resource "uptimeify_monitor_tag" "shop_production" { monitor_type = "website" monitor_id = tonumber(uptimeify_website.shop.id) tag_id = tonumber(uptimeify_tag.production.id) } ``` ## 3. Apply ```sh tofu init tofu plan tofu apply ``` With Terraform, use `terraform` instead of `tofu`, the commands are the same. The monitor appears in the dashboard right after `apply` and starts checking within its interval. ## 4. Change and review Edit the configuration, run `tofu plan` and review the diff like any other code change. A change somebody made in the dashboard shows up in the next `plan` as drift and is reset on `apply`. ## Next steps - [Customer tokens](/terraform/customer-tokens): one configuration per client. - [Import existing setup](/terraform/import): bring monitors you created in the dashboard under code. - [Secrets and updates](/terraform/secrets-and-updates): headers, passwords and how the provider sends updates. - [`uptimeify_website`](/terraform/resources/website): every attribute of the website monitor. ### Import existing setup URL: https://docs.uptimeify.io/terraform/import Description: Bring monitors, status pages and incident management you created in the dashboard under OpenTofu or Terraform with import. Summary: Every resource supports import. You do not have to start from scratch: create the configuration for what already exists and let `plan` confirm it matches. ## Import block (recommended) ```terraform to = uptimeify_website.shop id = "42" } ``` ```sh tofu plan -generate-config-out=generated.tf ``` OpenTofu and Terraform write the configuration of every imported resource into `generated.tf`. Review it, move it where it belongs and run `tofu apply` to complete the import. ## Import command ```sh tofu import uptimeify_website.shop 42 ``` ## Which id to use | Resource | Import id | | --- | --- | | Monitors, customers, tags, maintenance windows, notification channels, status pages | numeric id or public id (UUID) | | Child objects | `/`, for example `/` or `/` | | [`monitor_tag`](/terraform/resources/monitor_tag) | `//` | | One per organization (`organization_settings`, `im_org_settings`, `smtp_settings`, `sso_oidc`, ...) | any id, the token's organization is used | The exact format is on each resource page under **Import**. ## After the import Write-only secrets (headers, request bodies, passwords, HMAC keys) are never returned by the API and therefore not imported. Set them in the configuration together with their `*_wo_version`, see [Secrets and updates](/terraform/secrets-and-updates). ### uptimeify_custom_field URL: https://docs.uptimeify.io/terraform/resources/custom_field Description: A custom field of the customer master data (organization token with write access). The API never deletes a field: destroying it deactivates it, and creating a field whose field_key belongs to a deactivated one reactivates that field (same id) with the configured values, so customer values stored under the key come back. An active field with the key answers 409; import it instead. A field deactivated outside Terraform counts as gone. Import with the numeric id. Summary: A custom field of the customer master data (organization token with write access). The API never deletes a field: destroying it deactivates it, and creating a field whose `field_key` belongs to a deactivated one reactivates that field (same id) with the configured values, so customer values stored under the key come back. An active field with the key answers 409; import it instead. A field deactivated outside Terraform counts as gone. Import with the numeric id. ## Example Usage ```terraform resource "uptimeify_custom_field" "contract" { name = "Contract" field_key = "contract" } resource "uptimeify_custom_field" "tier" { name = "Support tier" field_type = "select" options = ["basic", "premium"] } ``` ## Schema ### Required - `name` (String) ### Optional - `display_order` (Number) - `field_key` (String) Key in the customer's `custom_fields`: lower-case letters, digits, single underscores. Unset = derived from `name`. - `field_type` (String) `text`, `number`, `email`, `url`, `select`. Default `text`. - `help_text` (String) - `is_required` (Boolean) - `options` (List of String) Choices of a `select` field, at most 50 of up to 100 characters. - `placeholder` (String) - `show_in_table` (Boolean) Show as a column in the customer list. ### Read-Only - `created_at` (String) - `id` (String) Numeric field id. - `organization_id` (Number) - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell terraform import uptimeify_custom_field.contract 5 ``` ### uptimeify_customer URL: https://docs.uptimeify.io/terraform/resources/customer Description: A customer of the organization. Needs an organization token with write access (customer tokens cannot create customers). Destroying it deletes the customer with its monitors and history. Import with the numeric id or the public id. delete_user_action cannot be read back; the permission overrides are read back only with a token that may write them, otherwise they stay unset after an import. Summary: A customer of the organization. Needs an organization token with write access (customer tokens cannot create customers). Destroying it deletes the customer with its monitors and history. Import with the numeric id or the public id. `delete_user_action` cannot be read back; the permission overrides are read back only with a token that may write them, otherwise they stay unset after an import. ## Example Usage ```terraform resource "uptimeify_customer" "shop" { name = "Example Shop GmbH" package_type = "business" # or package_id = 3 notification_email = "ops@example-shop.com" custom_fields = jsonencode({ contract = "A-1" }) notification_targets = { email = "customer", sms = "organization" } allow_self_service = true } ``` ## Schema ### Required - `name` (String) ### Optional - `allow_self_service` (Boolean) Customer logins may add their own monitors. Unset = package default. Only an organization admin token with unrestricted customer scope sets and reads it (otherwise the API ignores it and leaves it out of the answer, so changes made outside Terraform are not detected). - `can_edit_managed` (Boolean) Customer logins may edit managed monitors. Only an organization admin token with unrestricted customer scope sets and reads it (otherwise the API ignores it and leaves it out of the answer, so changes made outside Terraform are not detected). - `company_name` (String) - `custom_fields` (String) Values of the organization's custom fields as a JSON object (`jsonencode({ contract = "A-1" })`), keyed by `field_key`. Replaced as a whole. - `delete_user_action` (String) On destroy, logins assigned only to this customer are `deactivate`d (default) or `delete`d. - `email` (String) Contact email of the customer. - `email_language` (String) Language of mails to this customer. Unset = organization language. - `enable_email_alerts` (Boolean) Whether the organization's own email notifications alert about this customer. Covers only notifications to the organization (its own channels and the organization recipient of the email/SMS fallback); channels the customer created in their own account are never affected, the customer stops those by disabling or deleting them. A set value replaces the package value for this customer. Unset = package default. Only an organization admin token with unrestricted customer scope sets and reads it (otherwise the API ignores it and leaves it out of the answer, so changes made outside Terraform are not detected). - `enable_integration_alerts` (Boolean) Whether the organization's own integration notifications (Slack, PagerDuty, ...) alert about this customer. Covers only notifications to the organization (its own channels and the organization recipient of the email/SMS fallback); channels the customer created in their own account are never affected, the customer stops those by disabling or deleting them. A set value replaces the package value for this customer. Unset = package default. Only an organization admin token with unrestricted customer scope sets and reads it (otherwise the API ignores it and leaves it out of the answer, so changes made outside Terraform are not detected). - `enable_post_request_escalation` (Boolean) POST request escalation. Unset = package default. Only an organization admin token with unrestricted customer scope sets and reads it (otherwise the API ignores it and leaves it out of the answer, so changes made outside Terraform are not detected). - `enable_sms_alerts` (Boolean) Whether the organization's own SMS notifications alert about this customer. Covers only notifications to the organization (its own channels and the organization recipient of the email/SMS fallback); channels the customer created in their own account are never affected, the customer stops those by disabling or deleting them. A set value replaces the package value for this customer. Exception: SMS through the customer's own channels still counts against the package's monthly SMS limit per customer and the organization's… ### uptimeify_customer_domain URL: https://docs.uptimeify.io/terraform/resources/customer_domain Description: A domain of a customer whose registration expiry is watched over RDAP. The top-level domain must support RDAP. Creating one that already exists with the same values fails; import it instead. Import with the numeric id or the public id. Summary: A domain of a customer whose registration expiry is watched over RDAP. The top-level domain must support RDAP. Creating one that already exists with the same values fails; import it instead. Import with the numeric id or the public id. ## Example Usage ```terraform resource "uptimeify_customer_domain" "shop" { customer_id = tonumber(uptimeify_customer.shop.id) domain_name = "example-shop.com" expiry_warning_days = 45 } ``` ## Schema ### Required - `customer_id` (Number) - `domain_name` (String) Registered domain without protocol, lower case, e.g. `example.com`. ### Optional - `expiry_error_days` (Number) Alert this many days before expiry, 1 to 90. - `expiry_warning_days` (Number) Warn this many days before expiry, 1 to 365. - `label` (String) - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer-scoped tokens always create `self_service` entries, everyone else gets `managed` when unset. - `status` (String) `active` (checked, counts against the monitor quota) or `disabled`. ### Read-Only - `created_at` (String) - `id` (String) Numeric id. - `public_id` (String) - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id terraform import uptimeify_customer_domain.shop 9 ``` ### uptimeify_customer_ip URL: https://docs.uptimeify.io/terraform/resources/customer_ip Description: An IP address of a customer, checked against DNS blocklists (DNSBL). Creating one that already exists with the same values fails; import it instead. Import with the numeric id or the public id. Summary: An IP address of a customer, checked against DNS blocklists (DNSBL). Creating one that already exists with the same values fails; import it instead. Import with the numeric id or the public id. ## Example Usage ```terraform resource "uptimeify_customer_ip" "mail" { customer_id = tonumber(uptimeify_customer.shop.id) ip_address = "203.0.113.25" label = "Mail server" } ``` ## Schema ### Required - `customer_id` (Number) - `ip_address` (String) IPv4 or IPv6 address, lower case. ### Optional - `ip_family` (String) `v4` or `v6`; derived from the address when unset. - `label` (String) - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer-scoped tokens always create `self_service` entries, everyone else gets `managed` when unset. - `status` (String) `active` (checked, counts against the IP quota) or `disabled`. ### Read-Only - `created_at` (String) - `id` (String) Numeric id. - `public_id` (String) - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id terraform import uptimeify_customer_ip.mail 7 ``` ### uptimeify_dns_monitor URL: https://docs.uptimeify.io/terraform/resources/dns_monitor Description: A DNS monitor: resolves hostname and compares the answers per record type with expected_values. Import with the numeric id or the public id. Summary: A DNS monitor: resolves `hostname` and compares the answers per record type with `expected_values`. Import with the numeric id or the public id. ## Example Usage ```terraform data "uptimeify_customer" "shop" { name = "Example Shop GmbH" } resource "uptimeify_dns_monitor" "this" { customer_id = data.uptimeify_customer.shop.id name = "shop.example MX" hostname = "shop.example" record_types = ["A", "MX"] match_mode = "contains" expected_values = { A = ["203.0.113.10"] MX = ["10 mail.shop.example."] } allowed_check_country_codes = ["DE", "NL"] } ``` ## Schema ### Required - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `expected_values` (Map of List of String) Expected answers per record type (upper-case key); every type in `record_types` needs at least one value. Values unique and without surrounding spaces. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `match_mode` (String) `exact` (answer set equals the expected values) or `contains` (answer includes them). - `name` (String) Display name, 1 to 255 characters. - `record_types` (List of String) Record types to resolve, upper case and unique, e.g. `["A", "MX"]`. ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `allow_duplicate` (Boolean, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Create the monitor even if the customer already has one of this type for the same target. Without it the create fails with 409 `monitorAlreadyExists` and the error names the import command for the existing monitor. Sent with create only. - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `require_expected_values` (Boolean) Defaults to false. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. - `trigger_on_mismatch` (Boolean) Alert when the answers do not match. Defaults to true. - `trigger_on_resolve_error` (Boolean) Alert when the name does not resolve. Defaults to true. ### Read-Only - `created_at` (String) - `id` (String) Numeric DNS monitor id. - `organization_id` (Number) - `public_id` (String) Public UUID of the DNS monitor. - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id terraform import uptimeify_dns_monitor.this 42 ``` ### uptimeify_escalation_config URL: https://docs.uptimeify.io/terraform/resources/escalation_config Description: The organization's escalation webhook (one per organization; organization token with write access). Creating it adopts the stored configuration and applies the configured values. The webhook URL also drives the organization webhook channel (Organization Webhook), so do not manage that channel as uptimeify_notification_channel too. Destroying it sets is_active = false and clears the URL, which deactivates the organization-level webhook channels; the row stays. Import with the organization id. Summary: The organization's escalation webhook (one per organization; organization token with write access). Creating it adopts the stored configuration and applies the configured values. The webhook URL also drives the organization webhook channel (`Organization Webhook`), so do not manage that channel as `uptimeify_notification_channel` too. Destroying it sets `is_active = false` and clears the URL, which deactivates the organization-level webhook channels; the row stays. Import with the organization id. ## Example Usage ```terraform variable "escalation_token" { type = string sensitive = true } resource "uptimeify_escalation_config" "this" { webhook_url = "https://hooks.example.com/uptimeify" webhook_method = "POST" webhook_timeout = 10 expected_status_codes = "200,202,204" is_active = true webhook_headers_wo = { "X-Api-Token" = var.escalation_token } webhook_headers_wo_version = 1 } ``` ## Schema ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `expected_status_codes` (String) Comma-separated, e.g. `200,201,202,204`. Unset = keep. - `is_active` (Boolean) - `organization_id` (Number) Unset = the token's organization. - `webhook_body_template` (String) JSON template with placeholders such as `{{websiteName}}`. Unset = keep. - `webhook_headers_wo` (Map of String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only request headers (they may carry tokens). Sent with create and whenever `webhook_headers_wo_version` changes; replaces all stored headers. Authorization, Cookie, Host, X-Forwarded-* and Proxy-* are refused by the API. - `webhook_headers_wo_version` (Number) Change to resend `webhook_headers_wo`. - `webhook_method` (String) `POST`, `PUT` or `PATCH`. Unset = keep (default `POST`). - `webhook_retry_attempts` (Number) 0 to 10. Unset = keep (default 3). - `webhook_retry_delay` (Number) Seconds, 0 to 60. Unset = keep (default 60). - `webhook_timeout` (Number) Seconds, 1 to 30. Unset = keep (default 30). - `webhook_url` (String) Target URL (http/https, must resolve to a public address). Give it normalized (as `new URL()` prints it, e.g. with the trailing `/` of a bare host). Unset clears it and switches the organization webhook channel off. ### Read-Only - `id` (String) The organization id. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # The organization id terraform import uptimeify_escalation_config.this 2 ``` ### uptimeify_ftp_monitor URL: https://docs.uptimeify.io/terraform/resources/ftp_monitor Description: An FTP monitor: logs in (check_mode protocol) or only checks the port (tcp). The hostname must resolve to a public address. Import with the numeric id or the public id. Summary: An FTP monitor: logs in (check_mode `protocol`) or only checks the port (`tcp`). The hostname must resolve to a public address. Import with the numeric id or the public id. ## Example Usage ```terraform variable "ftp_password" { type = string sensitive = true } resource "uptimeify_ftp_monitor" "this" { customer_id = 12 name = "Upload server" hostname = "ftp.shop.example" user = "monitor" tls_mode = "explicit" password_wo = var.ftp_password password_wo_version = 1 } ``` ## Schema ### Required - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `name` (String) Display name, 1 to 255 characters. ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `allow_duplicate` (Boolean, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Create the monitor even if the customer already has one of this type for the same target. Without it the create fails with 409 `monitorAlreadyExists` and the error names the import command for the existing monitor. Sent with create only. - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `check_mode` (String) `protocol` (full login check, credentials required) or `tcp` (port reachability only; the API then stores no protocol settings and no credentials). Defaults to `protocol`. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `password_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Login password. Required in check_mode `protocol`. Write-only (Terraform 1.11+ / OpenTofu 1.11+), never stored in state or returned by the API; sent on create and whenever the matching `*_wo_version` changes. - `password_wo_version` (Number) Change this number to send `password_wo` again. - `port` (Number) TCP port. Unset = 990 with tls_mode `implicit`, else 21. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. - `tls_mode` (String) `none` (plain FTP), `explicit` (AUTH TLS) or `implicit` (FTPS). Defaults to `none`. - `user` (String) Login user. Required in check_mode `protocol`. ### Read-Only - `created_at` (String) - `id` (String) Numeric FTP monitor id. - `organization_id` (Number) - `public_id` (String) Public UUID of the FTP monitor. - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id terraform import uptimeify_ftp_monitor.this 42 ``` ### uptimeify_icmp_monitor URL: https://docs.uptimeify.io/terraform/resources/icmp_monitor Description: An ICMP (ping) monitor. The hostname must resolve to a public address when it is set. Import with the numeric id or the public id. Summary: An ICMP (ping) monitor. The hostname must resolve to a public address when it is set. Import with the numeric id or the public id. ## Example Usage ```terraform resource "uptimeify_icmp_monitor" "this" { customer_id = 12 name = "Edge router" hostname = "gw.shop.example" ping_count = 3 } ``` ## Schema ### Required - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `name` (String) Display name, 1 to 255 characters. ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `allow_duplicate` (Boolean, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Create the monitor even if the customer already has one of this type for the same target. Without it the create fails with 409 `monitorAlreadyExists` and the error names the import command for the existing monitor. Sent with create only. - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `packet_size` (Number) Payload size in bytes, 1 to 65507. Unset = worker default. - `ping_count` (Number) Echo requests per check, 1 to 10. Unset = worker default. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. ### Read-Only - `created_at` (String) - `id` (String) Numeric ICMP monitor id. - `organization_id` (Number) - `public_id` (String) Public UUID of the ICMP monitor. - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id terraform import uptimeify_icmp_monitor.this 42 ``` ### uptimeify_im_alert_source URL: https://docs.uptimeify.io/terraform/resources/im_alert_source Description: An Incident Management alert source (inbound integration). Incident Management must be active for the organization. Import with the numeric id; the server-minted tokens are shown by the API only once and are therefore null after an import until rotated. Summary: An Incident Management alert source (inbound integration). Incident Management must be active for the organization. Import with the numeric id; the server-minted tokens are shown by the API only once and are therefore null after an import until rotated. ## Example Usage ```terraform variable "grafana_hmac_secret" { type = string sensitive = true } # Grafana webhook with the preset mapping, HMAC signature and a weekly quiet window. resource "uptimeify_im_alert_source" "grafana" { team_id = 7 name = "Grafana production" type = "grafana" # Write-only: never stored in state. Bump the version to send a new secret. hmac_secret_wo = var.grafana_hmac_secret hmac_secret_wo_version = 1 maintenance_windows = [{ days_of_week = [7], from = "02:00", to = "04:00", timezone = "Europe/Berlin" }] } # Custom webhook with a v2 attribute mapping and bearer auth. resource "uptimeify_im_alert_source" "custom" { team_id = 7 name = "Billing jobs" type = "custom" bearer_enabled = true # Change to rotate the bearer token or the ingest token. bearer_token_rotation = "2026-10" ingest_token_rotation = "2026-10" payload_mapping = { default_severity = "sev3" attributes = [ { key = "title", standard = true, steps = [{ kind = "extract", type = "path", expr = "job.name" }] }, { key = "severity", standard = true, steps = [ { kind = "extract", type = "path", expr = "level" }, { kind = "valueMap", entries = [{ from = "fatal", to = "sev1" }, { from = "error", to = "sev2" }], fallback = "sev3" }, ] }, ] } } output "billing_webhook_url" { value = uptimeify_im_alert_source.custom.ingest_url sensitive = true } ``` ## Schema ### Required - `name` (String) 1 to 200 characters, no surrounding whitespace. - `team_id` (Number) Team that owns incidents from this source. - `type` (String) A preset name from `GET /api/im/sources/presets` (e.g. `zabbix`, `datadog`, `grafana`, `alertmanager`, `sentry`, `beszel`, `custom`), `api` (no webhook URL, fed by `POST /api/im/events`) or `email`. Changing it replaces the source. ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `auto_resolve` (Boolean) Resolve the incident when the vendor sends a resolve. Default `true`. - `bearer_enabled` (Boolean) Require `Authorization: Bearer `. Enabling it the first time mints the token. - `bearer_token_rotation` (String) Any value; changing it mints a new bearer token (the old one stops working at once) and enables bearer auth. - `grouping_window_minutes` (Number) Group alerts arriving within this many minutes into one incident. Unset = group by dedup key only. - `hmac_enabled` (Boolean) Require an HMAC signature. Enabling needs a secret: set `hmac_secret_wo` (once is enough, disabling keeps the secret stored). - `hmac_secret_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only HMAC secret, at least 16 characters. Sent with create and whenever `hmac_secret_wo_version` changes; it also enables HMAC. A new secret replaces the old one at once (no grace period). - `hmac_secret_wo_version` (Number) Change to resend `hmac_secret_wo`. - `ingest_token_rotation` (String) Any value; changing it rotates the ingest token. The old token keeps working until `secondary_expires_at`. - `maintenance_windows` (Attributes List) Recurring windows in which alerts are stored as suppressed instead of opening incidents. At most 20. (see [below for nested schema](#nested-schema-for-maintenance_windows)) - `payload_mapping` (Attributes) How a vendor payload becomes an alert. Either the v2 `attributes` list or the v1 selector fields (`title`, `severity`, `status`, ...). Unset = not managed: the server keeps its mapping (a preset type starts with the preset mapping; read it with the data source); removing the block later keeps the last mapping. An import reads the stored mapping. Must stay uns… ### uptimeify_im_channel URL: https://docs.uptimeify.io/terraform/resources/im_channel Description: An Incident Management paging channel (Slack incoming webhook, generic webhook or email). Escalation tiers and the organization fallback page through it. Incident Management must be active for the organization. The webhook URL and header values are secrets: the API never returns them, so they are write-only here. Import with the numeric id. Summary: An Incident Management paging channel (Slack incoming webhook, generic webhook or email). Escalation tiers and the organization fallback page through it. Incident Management must be active for the organization. The webhook URL and header values are secrets: the API never returns them, so they are write-only here. Import with the numeric id. ## Example Usage ```terraform variable "slack_webhook_url" { type = string sensitive = true } # Organization-wide Slack channel, also usable as the escalation fallback. resource "uptimeify_im_channel" "ops_slack" { name = "Ops Slack" type = "slack" webhook_url_wo = var.slack_webhook_url secrets_wo_version = 1 # bump to resend the URL after rotating it } # Team-scoped email channel. resource "uptimeify_im_channel" "dba_mail" { name = "DBA mailbox" type = "email" team_id = 9 email = "dba-oncall@example.com" } resource "uptimeify_im_org_settings" "this" { fallback_channel_id = tonumber(uptimeify_im_channel.ops_slack.id) } ``` ## Schema ### Required - `name` (String) 1 to 120 characters, no surrounding whitespace. - `type` (String) `webhook`, `slack` or `email`. ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `email` (String) `type = "email"`: recipient address (required there). - `headers_wo` (Map of String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) `webhook`/`slack`: extra request headers (no `Host`). Write-only: sent on create and whenever `secrets_wo_version` changes, then replacing the stored set (unset = remove all). The names are readable as `header_names`. - `is_active` (Boolean) Default `true`. The organization fallback channel cannot be deactivated. - `secrets_wo_version` (Number) Change to resend `webhook_url_wo` and `headers_wo`. - `team_id` (Number) Team of the organization; unset = organization-wide channel. - `webhook_url_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) `webhook`/`slack`: public http(s) URL, required on create. Write-only: sent on create, on a `type` change and whenever `secrets_wo_version` changes. ### Read-Only - `created_at` (String) - `has_webhook_url` (Boolean) Whether a webhook URL is stored. - `header_names` (List of String) Names of the stored headers, sorted (values are never returned). - `id` (String) Numeric channel id. - `organization_id` (Number) - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell terraform import uptimeify_im_channel.ops_slack 12 ``` ### uptimeify_im_escalation_tier URL: https://docs.uptimeify.io/terraform/resources/im_escalation_tier Description: An escalation tier of an Incident Management team. Creating a tier also creates its default schedule (default_schedule_id, rotation mode none) whose single rotation is member_user_ids; further schedules of the tier are uptimeify_im_schedule. Import with /. Summary: An escalation tier of an Incident Management team. Creating a tier also creates its default schedule (`default_schedule_id`, rotation mode `none`) whose single rotation is `member_user_ids`; further schedules of the tier are `uptimeify_im_schedule`. Import with `/`. ## Example Usage ```terraform resource "uptimeify_im_escalation_tier" "first" { team_id = uptimeify_im_team.platform.id tier_order = 1 member_user_ids = [uptimeify_im_team_member.alice.user_id] auto_escalation_after_minutes = 10 auto_escalation_severities = ["critical", "warning"] # Escalate automatically only on weekdays, office hours. auto_escalation_time_filters = [ { from = "08:00", until = "18:00", days = [1, 2, 3, 4, 5] }, ] } resource "uptimeify_im_escalation_tier" "second" { team_id = uptimeify_im_team.platform.id tier_order = 2 member_user_ids = [uptimeify_im_team_member.bob.user_id] } ``` ## Schema ### Required - `member_user_ids` (List of String) Team members on the default schedule's rotation, in order (1 to 200 user ids). Changing it replaces all rotation groups of the default schedule. - `team_id` (Number) ### Optional - `auto_escalation_after_minutes` (Number) Minutes before escalating to the next tier. Default `5`. - `auto_escalation_enabled` (Boolean) Default `true`. - `auto_escalation_severities` (Set of String) Severities that escalate: `critical`, `warning`, `minor`. Unset = all. - `auto_escalation_stop_mode` (String) `acknowledged` or `resolved`. Default `acknowledged`. - `auto_escalation_time_filters` (Attributes List) Weekly windows in which auto-escalation runs. Empty (default) = always. (see [below for nested schema](#nested-schema-for-auto_escalation_time_filters)) - `repeats` (Number) Extra pages on this tier before moving on. Default `0`. - `repeats_after_minutes` (Number) Minutes between repeats; unset = `auto_escalation_after_minutes`. - `repeats_stop_mode` (String) `acknowledged` or `resolved`. Default `acknowledged`. - `tier_order` (Number) Position in the team's ladder, 1 = paged first. Unset = appended at the end. On create the tier is inserted there (tiers at or after it move down by one); a later change reorders the team's tiers (POST .../tiers/reorder). Both move the other tiers too: when you set it, set it on every tier of the team, as 1..n. A value larger than the number of tiers ends up as the last position. ### Read-Only - `default_schedule_id` (Number) Schedule the API created with the tier. Do not also manage it as `uptimeify_im_schedule`. - `id` (String) `/`. - `tier_id` (Number) Numeric tier id. ### Nested Schema for `auto_escalation_time_filters` Required: - `days` (List of Number) ISO weekdays, 1 = Monday to 7 = Sunday. - `from` (String) `HH:mm`. - `until` (String) `HH:mm` or `24:00`. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # / terraform import uptimeify_im_escalation_tier.first 12/56 ``` ### uptimeify_im_org_settings URL: https://docs.uptimeify.io/terraform/resources/im_org_settings Description: Incident Management settings of the token's organization (one per organization). Creating it adopts the existing settings and applies the configured values; destroying it only removes it from the state, the settings stay. Import with any id, e.g. org. Summary: Incident Management settings of the token's organization (one per organization). Creating it adopts the existing settings and applies the configured values; destroying it only removes it from the state, the settings stay. Import with any id, e.g. `org`. ## Example Usage ```terraform # One per organization; destroy only removes it from the state. resource "uptimeify_im_org_settings" "this" { monitoring_bridge = "both" overage_enabled = false fallback_channel_id = 3 } ``` ## Schema ### Optional - `fallback_channel_id` (Number) Active Incident Management channel paged when an escalation runs out. Unset clears it. - `monitoring_bridge` (String) Where classic monitoring alerts go: `im_only`, `classic_only` or `both`. Unset = keep the current value. - `overage_enabled` (Boolean) Allow Incident Management usage beyond the plan (billed as overage). Unset = keep the current value. ### Read-Only - `enabled` (Boolean) Whether Incident Management is active (`POST /api/im/activate`; read only here). - `id` (String) The organization id. - `organization_id` (Number) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Any id works: the settings belong to the token's organization. terraform import uptimeify_im_org_settings.this org ``` ### uptimeify_im_outbound_integration URL: https://docs.uptimeify.io/terraform/resources/im_outbound_integration Description: An Incident Management outbound integration: forwards incident events to Slack, Microsoft Teams, Discord, Jira, PagerDuty (Events v2), Opsgenie or a generic webhook. Incident Management must be active for the organization. URLs, tokens, keys and header values are secrets the API never returns, so they are write-only here; has_* tells whether one is stored. Import with the numeric id. Summary: An Incident Management outbound integration: forwards incident events to Slack, Microsoft Teams, Discord, Jira, PagerDuty (Events v2), Opsgenie or a generic webhook. Incident Management must be active for the organization. URLs, tokens, keys and header values are secrets the API never returns, so they are write-only here; `has_*` tells whether one is stored. Import with the numeric id. ## Example Usage ```terraform variable "teams_webhook_url" { type = string sensitive = true } variable "jira_api_token" { type = string sensitive = true } # Post every sev1/sev2 incident event of the platform team to a Microsoft Teams channel. resource "uptimeify_im_outbound_integration" "teams" { name = "Platform Teams" type = "teams" team_id = 7 filter_severities = ["sev1", "sev2"] webhook_url_wo = var.teams_webhook_url secrets_wo_version = 1 } # Open a Jira issue per new incident (the server default event_kinds for jira). resource "uptimeify_im_outbound_integration" "jira" { name = "Jira OPS" type = "jira" email = "bot@example.com" base_url = "https://example.atlassian.net" project_key = "OPS" api_token_wo = var.jira_api_token } ``` ## Schema ### Required - `name` (String) 1 to 200 characters, no surrounding whitespace. - `type` (String) `slack`, `teams`, `discord`, `jira`, `pagerduty_v2`, `opsgenie` or `webhook`. Changing it replaces the integration. ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `api_key_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) `opsgenie`: API key, required. Write-only: sent on create and whenever `secrets_wo_version` changes. - `api_token_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) `jira`: API token, required. Write-only: sent on create and whenever `secrets_wo_version` changes. - `base_url` (String) `jira`: site URL, https only, required. - `bearer_token_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) `webhook`: sent as `Authorization: Bearer`. Write-only: sent on create and whenever `secrets_wo_version` changes. - `email` (String) `jira`: account email, required. - `event_kinds` (List of String) Events to forward: `incident_created`, `acknowledged`, `severity_changed`, `status_changed`, `comment`, `resolved`. Unset = all, except `jira`, where the server stores `["incident_created"]`. Removing it from the configuration keeps the stored list. - `filter_severities` (List of String) Only these severities, `sev1` to `sev4`. Unset = all. - `filter_team_ids` (List of Number) Only incidents of these teams (of the organization). Unset = all. - `headers_wo` (Map of String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) `webhook`: extra request headers. Write-only: sent on create and whenever `secrets_wo_version` changes, then replacing the stored set (unset = remove all). - `is_active` (Boolean) Default `true`. - `project_key` (String) `jira`: project key, required. - `routing_key_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) `pagerduty_v2`: integration routing key, required. Write-only: sent on create and whenever `secrets_wo_version` changes. - `secrets_wo_version` (Number) Change to resend every `*_wo` value. - `team_id` (Number) Owning team; unset = organization-wide (needs an org admin). - `webhook_url_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) `slack`/`teams`/`discord`/`webhook`: target URL (public http(s)), required. Write-only: sent on create and whenever `secrets_wo_version` changes. ### Rea… ### uptimeify_im_routing_rule URL: https://docs.uptimeify.io/terraform/resources/im_routing_rule Description: An Incident Management routing rule: incidents whose alert matches go to team_id. Rules run in ascending priority. Incident Management must be active for the organization. Import with the numeric id. Summary: An Incident Management routing rule: incidents whose alert matches go to `team_id`. Rules run in ascending `priority`. Incident Management must be active for the organization. Import with the numeric id. ## Example Usage ```terraform # Critical database alerts from Grafana go to the DBA team as sev1. resource "uptimeify_im_routing_rule" "db" { team_id = 9 priority = 10 match = { source_ids = [tonumber(uptimeify_im_alert_source.grafana.id)] severity = ["sev1", "sev2"] tags = ["db"] field_matches = { env = "prod" } } severity_override = "sev1" } # Catch-all at the end. resource "uptimeify_im_routing_rule" "default" { team_id = 7 priority = 1000 } ``` ## Schema ### Required - `team_id` (Number) The team that receives matching incidents. ### Optional - `match` (Attributes) What the rule matches; all set fields must match. Unset or `{}` = catch-all. All ids must belong to the organization. (see [below for nested schema](#nested-schema-for-match)) - `priority` (Number) Lower runs first. Default `100`. - `severity_override` (String) Unset = keep the mapped severity. ### Read-Only - `created_at` (String) - `id` (String) Numeric rule id. - `organization_id` (Number) - `updated_at` (String) ### Nested Schema for `match` Optional: - `customer_ids` (List of Number) Customer ids. At most 500. - `field_matches` (Map of String) Payload field -> expected value, at most 50 entries. - `monitor_ids` (List of Number) Ids of any monitor type (website, DNS, ICMP, ...). At most 500. - `severity` (List of String) `sev1` to `sev4`. - `source_ids` (List of Number) Alert source ids. At most 500. - `tags` (List of String) Alert tags. At most 200. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell terraform import uptimeify_im_routing_rule.db 17 ``` ### uptimeify_im_schedule URL: https://docs.uptimeify.io/terraform/resources/im_schedule Description: An on-call schedule on an escalation tier (created via POST /api/im/tiers/{tierId}/schedules). Rotation members must be members of the tier's team. The tier's own default schedule belongs to uptimeify_im_escalation_tier. Import with the numeric schedule id. Summary: An on-call schedule on an escalation tier (created via `POST /api/im/tiers/{tierId}/schedules`). Rotation members must be members of the tier's team. The tier's own default schedule belongs to `uptimeify_im_escalation_tier`. Import with the numeric schedule id. ## Example Usage ```terraform # Weekly rotation, handover Monday 09:00 Berlin time. resource "uptimeify_im_schedule" "weekly" { tier_id = uptimeify_im_escalation_tier.first.tier_id name = "Weekly on-call" timezone = "Europe/Berlin" rotation_mode = "explicit" rotation_repeats = "weekly" starts_on_day_of_week = 1 starts_on_time = "09:00" rotations = [ { members = [uptimeify_im_team_member.alice.user_id] }, { members = [uptimeify_im_team_member.bob.user_id] }, ] } ``` ## Schema ### Required - `name` (String) 1 to 120 characters. - `tier_id` (Number) Escalation tier (`uptimeify_im_escalation_tier.x.tier_id`). Changing it replaces the schedule. - `timezone` (String) IANA zone the handovers and weekly windows are read in, e.g. `Europe/Berlin`. ### Optional - `auto_rotation_size` (Number) For mode `auto`: members per generated rotation group. - `custom_repeat_unit` (String) For `custom`: `minutes`, `hours`, `days`, `weeks` or `months`. - `custom_repeat_value` (Number) For `custom`: how many units. - `effective_from` (String) Start of validity. RFC3339 timestamp; unset = unbounded. The API answers in UTC with milliseconds, another spelling of the same instant is kept as written. - `effective_until` (String) End of validity. RFC3339 timestamp; unset = unbounded. The API answers in UTC with milliseconds, another spelling of the same instant is kept as written. - `rotation_mode` (String) `none` (default), `auto` or `explicit`. `auto` and `explicit` need `rotation_repeats` and `starts_on_time`. - `rotation_repeats` (String) `daily`, `weekly`, `biweekly`, `monthly` or `custom`; must be unset for mode `none`. - `rotations` (Attributes List) Ordered rotation groups (at most 50). Every member must be a member of the team. (see [below for nested schema](#nested-schema-for-rotations)) - `round_robin_size` (Number) Members on call at the same time. Default `1`. - `starts_on_date_of_month` (Number) Handover day 1-31 for monthly and custom-months rotations. - `starts_on_day_of_week` (Number) Handover weekday (ISO 1-7) for weekly, biweekly and custom-weeks rotations. - `starts_on_time` (String) Handover time `HH:mm`; required unless mode `none`. - `weekly_schedules` (Attributes List) Weekly windows the schedule covers. Empty (default) = around the clock. (see [below for nested schema](#nested-schema-for-weekly_schedules)) ### Read-Only - `id` (String) Numeric schedule id. - `team_id` (Number) Team of the tier. ### Nested Schema for `rotations` Required: - `members` (List of String) User ids in order, at most 200, no duplicates. ### Nested Schema for `weekly_schedules` Required: - `days` (List of Number) ISO weekdays, 1 = Monday to 7 = Sunday. - `from` (String) `HH:mm`. - `until` (String) `HH:mm` or `24:00`. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric schedule id terraform import uptimeify_im_schedule.weekly 78 ``` ### uptimeify_im_schedule_override URL: https://docs.uptimeify.io/terraform/resources/im_schedule_override Description: An override (vacation, swap) on an on-call schedule. Import with /. Summary: An override (vacation, swap) on an on-call schedule. Import with `/`. ## Example Usage ```terraform # Alice is on vacation, Bob covers. resource "uptimeify_im_schedule_override" "vacation" { schedule_id = uptimeify_im_schedule.weekly.id user_id = uptimeify_im_team_member.alice.user_id type = "offline" covered_by_user_ids = [uptimeify_im_team_member.bob.user_id] starts_at = "2030-08-01T00:00:00Z" ends_at = "2030-08-15T00:00:00Z" } ``` ## Schema ### Required - `ends_at` (String) End, after `starts_at`. RFC3339 timestamp. The API answers in UTC with milliseconds, another spelling of the same instant is kept as written. - `schedule_id` (Number) - `starts_at` (String) Start. RFC3339 timestamp. The API answers in UTC with milliseconds, another spelling of the same instant is kept as written. - `type` (String) `online` (user takes the shift) or `offline` (user is away). - `user_id` (String) User going online or offline; an admin, editor or responder of the organization. ### Optional - `apply_scope` (String) `this_team` (default) or `all_teams`. - `covered_by_user_ids` (Set of String) `offline` only: who covers (at most 200). Empty = a gap that auto fill-up backstops. - `escalation_tier_order` (Number) Only this tier position; unset = all tiers. ### Read-Only - `created_at` (String) - `id` (String) `/`. - `override_id` (Number) Numeric override id. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # / terraform import uptimeify_im_schedule_override.vacation 78/90 ``` ### uptimeify_im_service URL: https://docs.uptimeify.io/terraform/resources/im_service Description: A service of the Incident Management service catalog (\"Webshop\", \"Customer portal\") with its criticality, the responsible team and its monitors. An incident of a monitor that belongs to exactly one service is linked to that service. Needs an organization token of an organization admin. Import with the numeric id or the public id. Summary: A service of the Incident Management service catalog ("Webshop", "Customer portal") with its criticality, the responsible team and its monitors. An incident of a monitor that belongs to exactly one service is linked to that service. Needs an organization token of an organization admin. Import with the numeric id or the public id. ## Example Usage ```terraform resource "uptimeify_im_service" "webshop" { name = "Webshop" description = "Checkout and product pages." criticality = "critical" owner_team_id = tonumber(uptimeify_im_team.platform.id) monitors = [ { monitor_type = "website", monitor_id = tonumber(uptimeify_website.shop.id) }, { monitor_type = "tcp", monitor_id = tonumber(uptimeify_tcp_monitor.db.id) }, ] } ``` ## Schema ### Required - `name` (String) 1 to 200 characters, unique per organization regardless of case (409 `imServiceNameTaken`). ### Optional - `criticality` (String) `critical`, `high`, `medium` (default) or `low`. - `description` (String) Up to 2000 characters. - `monitors` (Attributes Set) The monitors of this service, at most 500. Terraform owns the whole set; unset = none. Each must belong to the organization (404 `imServiceMonitorNotFound`). A monitor deleted later drops out of the service and shows up as a diff. (see [below for nested schema](#nested-schema-for-monitors)) - `owner_team_id` (Number) Responsible team of the organization (404 `imTeamNotFound`). Deleting the team clears it. ### Read-Only - `created_at` (String) - `id` (String) Numeric service id. - `organization_id` (Number) - `public_id` (String) - `updated_at` (String) ### Nested Schema for `monitors` Required: - `monitor_id` (Number) Numeric id of the monitor within its type, e.g. `tonumber(uptimeify_website.shop.id)`. - `monitor_type` (String) `website` (also heartbeat and browser monitors), `dns`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp` or `imap_pop`. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric service id or public id terraform import uptimeify_im_service.webshop 12 ``` ### uptimeify_im_statuspage_rule URL: https://docs.uptimeify.io/terraform/resources/im_statuspage_rule Description: An Incident Management status page rule: incidents of team_id at min_severity or worse set the status page to target_state. Needs team-admin rights on the team (or organization admin). Manual overrides (POST /api/im/statuspage-rules/override) are an incident-time action and not managed by Terraform. Import with the numeric id. Summary: An Incident Management status page rule: incidents of `team_id` at `min_severity` or worse set the status page to `target_state`. Needs team-admin rights on the team (or organization admin). Manual overrides (`POST /api/im/statuspage-rules/override`) are an incident-time action and not managed by Terraform. Import with the numeric id. ## Example Usage ```terraform # sev1 incidents of the on-call team set the ACME status page to degraded, # and reset it when the incident resolves. message is the public text until the # incident gets its first status page update. resource "uptimeify_im_statuspage_rule" "acme" { team_id = tonumber(uptimeify_im_team.oncall.id) status_page_id = tonumber(uptimeify_status_page.acme.id) min_severity = "sev1" target_state = "degraded" auto_resolve = true message = "We are investigating an outage and will post updates here." } ``` ## Schema ### Required - `status_page_id` (Number) Numeric status page id of your organization. - `team_id` (Number) Incident Management team of your organization. ### Optional - `auto_resolve` (Boolean) Reset the page when the incident resolves. Default `true`. - `message` (String) Public text shown on the status page while this rule's override is active and the incident has no status page update yet. Up to 5000 characters, no surrounding whitespace (the API trims). Unset = no text. - `min_severity` (String) `sev1` (most severe) to `sev4`. Default `sev2`. - `target_state` (String) `warning` or `degraded` (default). ### Read-Only - `created_at` (String) - `id` (String) Numeric rule id. - `organization_id` (Number) - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell terraform import uptimeify_im_statuspage_rule.acme 17 ``` ### uptimeify_im_team URL: https://docs.uptimeify.io/terraform/resources/im_team Description: An Incident Management team. Needs Incident Management activated for the organization. Members, escalation tiers and schedules are separate resources. Import with the numeric id. Summary: An Incident Management team. Needs Incident Management activated for the organization. Members, escalation tiers and schedules are separate resources. Import with the numeric id. ## Example Usage ```terraform resource "uptimeify_im_team" "platform" { name = "Platform" timezone = "Europe/Berlin" escalation_repeats = 1 escalation_repeats_stop_mode = "acknowledged" engagement_report_enabled = true engagement_report_day_of_week = 1 engagement_report_time = "08:30" } ``` ## Schema ### Required - `name` (String) 1 to 120 characters, without surrounding spaces. ### Optional - `analytics_enabled` (Boolean) Default `false`. - `engagement_report_day_of_week` (Number) ISO weekday 1 (Monday) to 7. - `engagement_report_enabled` (Boolean) Default `false`. - `engagement_report_time` (String) `HH:mm`. - `escalation_repeats` (Number) How often the whole ladder repeats. Default `0`. - `escalation_repeats_after_minutes` (Number) Minutes before a ladder repeat. - `escalation_repeats_stop_mode` (String) `acknowledged` or `resolved`. Default `acknowledged`. - `label_color` (String) Free-form label color, e.g. `#43B1AE`. - `timezone` (String) IANA zone, default for new schedules of the team. Unset = organization default. ### Read-Only - `created_at` (String) - `id` (String) Numeric team id. - `organization_id` (Number) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric team id terraform import uptimeify_im_team.platform 12 ``` ### uptimeify_im_team_member URL: https://docs.uptimeify.io/terraform/resources/im_team_member Description: A member of an Incident Management team. Set user_id for an existing login (admin, editor or responder of the organization), or invite_email to invite by email (an unknown address gets a new account and an invitation mail). Import with /. Summary: A member of an Incident Management team. Set `user_id` for an existing login (admin, editor or responder of the organization), or `invite_email` to invite by email (an unknown address gets a new account and an invitation mail). Import with `/`. ## Example Usage ```terraform data "uptimeify_user" "alice" { email = "alice@example.com" } resource "uptimeify_im_team_member" "alice" { team_id = uptimeify_im_team.platform.id user_id = data.uptimeify_user.alice.id im_role = "admin" } # Invite by email: an unknown address gets an account and an invitation mail. resource "uptimeify_im_team_member" "bob" { team_id = uptimeify_im_team.platform.id invite_email = "bob@example.com" } ``` ## Schema ### Required - `team_id` (Number) ### Optional - `im_role` (String) `admin`, `member` or `stakeholder`. Default `member`. - `invite_email` (String) Invite by email instead of `user_id`; sends an invitation mail for a new address. Only used on create, not read back. - `user_id` (String) User id (see data source `uptimeify_user`). Changing it replaces the membership. ### Read-Only - `id` (String) `/`. - `member_id` (Number) Numeric membership id. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # / terraform import uptimeify_im_team_member.alice 12/34 ``` ### uptimeify_im_team_override URL: https://docs.uptimeify.io/terraform/resources/im_team_override Description: An override (vacation, swap) owned by an Incident Management team, optionally on one of its schedules. Import with /. Summary: An override (vacation, swap) owned by an Incident Management team, optionally on one of its schedules. Import with `/`. ## Example Usage ```terraform # Bob takes over for a release night, for the whole team. resource "uptimeify_im_team_override" "release" { team_id = uptimeify_im_team.platform.id user_id = uptimeify_im_team_member.bob.user_id type = "online" starts_at = "2030-09-01T18:00:00+02:00" ends_at = "2030-09-02T06:00:00+02:00" } ``` ## Schema ### Required - `ends_at` (String) End, after `starts_at`. RFC3339 timestamp. The API answers in UTC with milliseconds, another spelling of the same instant is kept as written. - `starts_at` (String) Start. RFC3339 timestamp. The API answers in UTC with milliseconds, another spelling of the same instant is kept as written. - `team_id` (Number) - `type` (String) `online` (user takes the shift) or `offline` (user is away). - `user_id` (String) User going online or offline; an admin, editor or responder of the organization. ### Optional - `apply_scope` (String) `this_team` (default) or `all_teams`. - `covered_by_user_ids` (Set of String) `offline` only: who covers (at most 200). Empty = a gap that auto fill-up backstops. - `escalation_tier_order` (Number) Only this tier position; unset = all tiers. - `schedule_id` (Number) A schedule of this team; unset = team-level override. ### Read-Only - `created_at` (String) - `id` (String) `/`. - `override_id` (Number) Numeric override id. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # / terraform import uptimeify_im_team_override.release 12/91 ``` ### uptimeify_imap_pop_monitor URL: https://docs.uptimeify.io/terraform/resources/imap_pop_monitor Description: An IMAP or POP3 monitor: logs in (check_mode protocol) or only checks the port (tcp, needs port). The hostname must resolve to a public address. Import with the numeric id or the public id. Summary: An IMAP or POP3 monitor: logs in (check_mode `protocol`) or only checks the port (`tcp`, needs `port`). The hostname must resolve to a public address. Import with the numeric id or the public id. ## Example Usage ```terraform variable "mailbox_password" { type = string sensitive = true } resource "uptimeify_imap_pop_monitor" "this" { customer_id = 12 name = "Support mailbox" hostname = "imap.shop.example" protocol = "imap" tls = true user = "support@shop.example" password_wo = var.mailbox_password password_wo_version = 1 } ``` ## Schema ### Required - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `name` (String) Display name, 1 to 255 characters. ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `allow_duplicate` (Boolean, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Create the monitor even if the customer already has one of this type for the same target. Without it the create fails with 409 `monitorAlreadyExists` and the error names the import command for the existing monitor. Sent with create only. - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `check_mode` (String) `protocol` (full login check, credentials required) or `tcp` (port reachability only; the API then stores no protocol settings and no credentials). Defaults to `protocol`. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `password_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Login password. Required in check_mode `protocol`. Write-only (Terraform 1.11+ / OpenTofu 1.11+), never stored in state or returned by the API; sent on create and whenever the matching `*_wo_version` changes. - `password_wo_version` (Number) Change this number to send `password_wo` again. - `port` (Number) TCP port. Unset = 993/143 for IMAP, 995/110 for POP3 (with/without `tls`); required in check_mode `tcp`. - `protocol` (String) `imap` or `pop3`. Defaults to `imap`. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. - `tls` (Boolean) Implicit TLS (IMAPS/POP3S). Defaults to false. - `tls_reject_unauthorized` (Boolean) Reject invalid server certificates. Defaults to true. - `user` (String) Login user. Required in check_mode `protocol`. ### Read-Only - `created_at` (String) - `id` (String) Numeric IMAP/POP3 monitor id. - `organization_id` (Number) - `public_id` (String) Public UUID of the IMAP/POP3 monitor. - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id terraform import uptimeify_imap_pop_monitor.this 42 ``` ### uptimeify_maintenance_window URL: https://docs.uptimeify.io/terraform/resources/maintenance_window Description: A maintenance window: alerts and incidents of its targets are suppressed while it runs. Set targets and/or tag_ids, or customer_id alone for the whole customer. A window with only organization-wide tags applies organization-wide. Import with the numeric id or the public id. Summary: A maintenance window: alerts and incidents of its targets are suppressed while it runs. Set `targets` and/or `tag_ids`, or `customer_id` alone for the whole customer. A window with only organization-wide tags applies organization-wide. Import with the numeric id or the public id. ## Example Usage ```terraform # Weekly Sunday-night window for every monitor tagged "production". resource "uptimeify_maintenance_window" "patch_night" { name = "Patch night" description = "OS updates" start_time = "2030-01-06T02:00:00+01:00" end_time = "2030-01-06T04:00:00+01:00" timezone = "Europe/Berlin" tag_ids = [tonumber(uptimeify_tag.production.id)] recurrence_pattern = { frequency = "weekly" days_of_week = [0] } } # One-off window for two explicit monitors. resource "uptimeify_maintenance_window" "migration" { name = "DB migration" start_time = "2030-03-01T22:00:00Z" end_time = "2030-03-02T01:00:00Z" targets = [ { type = "website", id = 12 }, { type = "dns", id = 7 }, ] } # Every monitor of one customer. resource "uptimeify_maintenance_window" "customer" { name = "Customer move" start_time = "2030-04-01T00:00:00Z" end_time = "2030-04-01T06:00:00Z" customer_id = 3 } ``` ## Schema ### Required - `end_time` (String) End, after start_time. RFC3339 timestamp. The API answers in UTC with milliseconds (`2030-01-01T02:00:00.000Z`); another spelling of the same instant is kept as written. - `name` (String) - `start_time` (String) Start. RFC3339 timestamp. The API answers in UTC with milliseconds (`2030-01-01T02:00:00.000Z`); another spelling of the same instant is kept as written. ### Optional - `customer_id` (Number) Whole-customer window: every monitor of this customer. Cannot be combined with `targets` or `tag_ids`; changing it replaces the window. - `description` (String) At most 2000 characters. - `is_active` (Boolean) Default `true`. - `recurrence_pattern` (Attributes) Repeat the window. Unset = one-off window. (see [below for nested schema](#nested-schema-for-recurrence_pattern)) - `tag_ids` (Set of Number) Numeric tag ids: every monitor carrying one of the tags is in maintenance. - `targets` (Attributes Set) Monitors the window applies to. All targets must belong to one customer. (see [below for nested schema](#nested-schema-for-targets)) - `timezone` (String) IANA zone the recurrence is read in, e.g. `Europe/Berlin`. Use the canonical name: the API stores aliases (`utc`, `Japan`) under their canonical spelling. Default `UTC`. ### Read-Only - `created_at` (String) - `id` (String) Numeric window id. - `public_id` (String) Public UUID of the window. - `updated_at` (String) ### Nested Schema for `recurrence_pattern` Required: - `frequency` (String) `daily`, `weekly` or `monthly`. Optional: - `day_of_month` (Number) Day of month, 1 to 31. - `days_of_week` (List of Number) Weekdays, 0 = Sunday to 6 = Saturday. - `end_recurrence_date` (String) Last date of the recurrence, e.g. `2031-12-31` or an RFC3339 timestamp. - `interval_count` (Number) Repeat every N units of frequency (2 with weekly = every other week), 1 to 365. The API treats unset as 1. ### Nested Schema for `targets` Required: - `id` (Number) Numeric id of the monitor. - `type` (String) One of `website`, `dns`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp`, `imap_pop`, `customer_domain`, `customer_ip`. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id terraform import uptimeify_maintenance_window.patch_night 42 ``` ### uptimeify_monitor_tag URL: https://docs.uptimeify.io/terraform/resources/monitor_tag Description: Puts one tag on one monitor. A monitor carries at most 5 tags. Import with //. Summary: Puts one tag on one monitor. A monitor carries at most 5 tags. Import with `//`. ## Example Usage ```terraform resource "uptimeify_monitor_tag" "shop_production" { monitor_type = "website" monitor_id = 12 tag_id = tonumber(uptimeify_tag.production.id) } ``` ## Schema ### Required - `monitor_id` (Number) Numeric id of the monitor. - `monitor_type` (String) One of `website`, `dns`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp`, `imap_pop`, `customer_domain`, `customer_ip`. - `tag_id` (Number) Numeric tag id. ### Read-Only - `id` (String) `//`. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # // terraform import uptimeify_monitor_tag.shop_production website/12/34 ``` ### uptimeify_notification_channel URL: https://docs.uptimeify.io/terraform/resources/notification_channel Description: A notification channel of the organization, or of one customer with customer_id. Secrets live in secret_config_wo and never enter the state. An active channel to the same recipient cannot exist twice (409). Website overrides are not managed here. Import with the numeric id. Summary: A notification channel of the organization, or of one customer with `customer_id`. Secrets live in `secret_config_wo` and never enter the state. An active channel to the same recipient cannot exist twice (409). Website overrides are not managed here. Import with the numeric id. ## Example Usage ```terraform resource "uptimeify_notification_channel" "ops_mail" { type = "email" name = "Ops mail" config = jsonencode({ email = "ops@example.com" }) } # Secrets go into the write-only attribute; bump the version to send a new one. variable "slack_webhook_url" { type = string sensitive = true } resource "uptimeify_notification_channel" "slack" { type = "slack" category = "integration" name = "Slack #alerts" customer_id = tonumber(uptimeify_customer.shop.id) config = jsonencode({}) secret_config_wo = jsonencode({ webhookUrl = var.slack_webhook_url }) secret_config_wo_version = 1 } ``` ## Schema ### Required - `config` (String) Provider settings without secrets, as a JSON object (`jsonencode({ email = "ops@example.com" })`). Keys removed here are cleared. - `name` (String) - `type` (String) Channel type: `email`, `sms`, `webhook`, `incident_management`, `slack`, `discord`, `teams`, `pagerduty`, `pushover`, `opsgenie`, `matrix`, `jira`, `allquiet`, `telegram`, `googlechat`, `mattermost`, `rocketchat`, `ntfy`, `gotify`, `ilert`, `grafanaoncall`, `incidentio`, `squadcast`, `github`, `gitlab`, `linear`, `servicenow`, `lark`, `dingtalk`, `wecom`. ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `allowed_package_types` (Set of String) Only customers with these package types get this channel. Unset = all packages. - `category` (String) `direct` (default) or `integration`. - `conditions` (String) Delivery conditions as a JSON object. Unset = always. - `customer_id` (Number) Channel of this customer. Unset = organization channel. - `delay_seconds` (Number) Wait before sending, 0 to 86400 seconds. - `is_active` (Boolean) - `secret_config_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only secret settings as a JSON object, stored encrypted. Sent with create and whenever `secret_config_wo_version` changes; keys left out keep their stored value. A secret cannot be removed (the API keeps the old value), replace the channel instead. Secret keys per type: `allquiet`: `webhookUrl`; `dingtalk`: `webhookUrl`; `discord`: `secret`, `webhookUrl`, `url`; `github`: `token`; `gitlab`: `token`; `googlechat`: `webhookUrl`; `gotify`: `appToken`; `grafanaoncall`: `webhookUrl`; `ilert`: `integrationKey`; `incidentio`: `token`; `jira`: `apiToken`; `lark`: `webhookUrl`; `linear`: `apiKey`; `matrix`: `accessToken`; `mattermost`: `webhookUrl`; `ntfy`: `accessToken`; `opsgenie`: `apiKey`; `pagerduty`: `routingKey`; `pushover`: `userKey`, `apiToken`; `rocketchat`: `webhookUrl`; `servicenow`: `password`; `slack`: `secret`, `webhookUrl`, `url`; `squadcast`: `webhookUrl`; `teams`: `webhookUrl`, `url`; `telegram`: `botToken`; `webhook`: `secret`, `webhookHeaders`, `headers`; `wecom`: `webhookUrl`. - `secret_config_wo_version` (Number) Change to resend `secret_config_wo`. ### Read-Only - `created_at` (String) - `id` (String) Numeric channel id. - `organization_id` (Number) - `secrets_set` (Map of Boolean) Which secrets are stored, e.g. `{ Secret = true }` (the API's `has` flags). ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell terraform import uptimeify_notification_channel.ops_mail 42 ``` ### uptimeify_notification_template URL: https://docs.uptimeify.io/terraform/resources/notification_template Description: The organization's default Incident Management notification chain (one per organization). It is copied to a user when their personal settings are first created; existing users keep theirs. Destroying switches the template off. Import with any id, e.g. org. Summary: The organization's default Incident Management notification chain (one per organization). It is copied to a user when their personal settings are first created; existing users keep theirs. Destroying switches the template off. Import with any id, e.g. `org`. ## Example Usage ```terraform # One per organization: the chain new users start with. Existing users keep theirs. resource "uptimeify_notification_template" "this" { rules = [ { urgency = "high", delay_minutes = 0, channel = "push" }, { urgency = "high", delay_minutes = 10, channel = "sms" }, { urgency = "low", delay_minutes = 0, channel = "email" }, ] } ``` ## Schema ### Required - `rules` (Attributes Set) The default chain. (see [below for nested schema](#nested-schema-for-rules)) ### Optional - `channels` (Map of Boolean) Delivery switches `push`, `sms`, `voice`, `email` for new users. Unset = on exactly for the channels the rules use. ### Read-Only - `id` (String) Always `org`. - `updated_at` (String) Last change of the template. ### Nested Schema for `rules` Required: - `channel` (String) `push`, `sms`, `voice` or `email`. `sms` and `voice` wait until the phone number is verified. - `delay_minutes` (Number) Minutes after the page starts, 0 to 1440. - `urgency` (String) `high` or `low`. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Any id works: the template belongs to the token's organization. terraform import uptimeify_notification_template.this org ``` ### uptimeify_organization_branding URL: https://docs.uptimeify.io/terraform/resources/organization_branding Description: White-label branding of the organization (one per organization): product name, colors, legal links, logos and favicons. Organization admins only. Destroying it resets name, colors, links and both flags and deletes the four images. Import with any id, e.g. branding; the image files are not imported. Summary: White-label branding of the organization (one per organization): product name, colors, legal links, logos and favicons. Organization admins only. Destroying it resets name, colors, links and both flags and deletes the four images. Import with any id, e.g. `branding`; the image files are not imported. ## Example Usage ```terraform resource "uptimeify_organization_branding" "this" { product_name = "ACME Monitoring" theme_primary = "#43B1AE" theme_secondary = "slate" imprint_url = "https://acme.example/imprint" privacy_url = "https://acme.example/privacy" # Local files; a changed file is uploaded again on the next apply. logo_light_file = "${path.module}/branding/logo-light.png" logo_dark_file = "${path.module}/branding/logo-dark.png" favicon_light_file = "${path.module}/branding/favicon.ico" } ``` ## Schema ### Optional - `favicon_dark_file` (String) Favicon (PNG or ICO, at most 512 KiB) for the dark theme: path of a local file. Uploaded when its content changes (see `favicon_dark_sha256`). Removing it deletes the uploaded image. - `favicon_light_file` (String) Favicon (PNG or ICO, at most 512 KiB) for the light theme: path of a local file. Uploaded when its content changes (see `favicon_light_sha256`). Removing it deletes the uploaded image. - `hide_logos` (Boolean) Show no logo at all. Default `false`. - `hide_product_name` (Boolean) Hide the product name next to the logo. Default `false`. - `imprint_url` (String) Link to your own imprint, `http://` or `https://`, up to 500 characters. - `logo_dark_file` (String) Logo (PNG, JPEG or WebP, at most 2 MiB) for the dark theme: path of a local file. Uploaded when its content changes (see `logo_dark_sha256`). Removing it deletes the uploaded image. - `logo_light_file` (String) Logo (PNG, JPEG or WebP, at most 2 MiB) for the light theme: path of a local file. Uploaded when its content changes (see `logo_light_sha256`). Removing it deletes the uploaded image. - `privacy_url` (String) Link to your own privacy policy, `http://` or `https://`, up to 500 characters. - `product_name` (String) Product name shown instead of Uptimeify, 1 to 80 characters. Unset = Uptimeify. - `terms_url` (String) Link to your own terms, `http://` or `https://`, up to 500 characters. - `theme_primary` (String) Primary color: uppercase hex `#RRGGBB` or a palette name (`brand`, `slate`, `gray`, `zinc`, `neutral`, `stone`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`). Unset = the default. - `theme_secondary` (String) Secondary color: uppercase hex `#RRGGBB` or a palette name (`brand`, `slate`, `gray`, `zinc`, `neutral`, `stone`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`). Unset = the default. ### Read-Only - `favicon_dark_sha256` (String) SHA-256 of `favicon_dark_file` at the last upload, read at plan time. - `favicon_light_sha256` (String) SHA-256 of `favicon_light_file` at the last upload, read at plan time. - `id` (String) The ID of this resource. - `logo_dark_sha256` (String) SHA-256 of `logo_dark_file` at the last upload, read at plan time. - `logo_light_sha256` (String) SHA-256 of `logo_light_file` at the last upload, read at plan time. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Any id; the image files are not imported terraform import uptimeify_organization_branding.this branding ``` ### uptimeify_organization_settings URL: https://docs.uptimeify.io/terraform/resources/organization_settings Description: Settings of the token's own organization (one per organization): name, billing address, MFA policy, SMS overage cap and notification defaults for new customers. Only the attributes you set are managed and sent, and only when they differ from the stored value. Creating it adopts the organization; destroying it only removes it from the state, nothing is reset. Plan, quota and payment are not managed here. Import with any id, e.g. org. Summary: Settings of the token's own organization (one per organization): name, billing address, MFA policy, SMS overage cap and notification defaults for new customers. Only the attributes you set are managed and sent, and only when they differ from the stored value. Creating it adopts the organization; destroying it only removes it from the state, nothing is reset. Plan, quota and payment are not managed here. Import with any id, e.g. `org`. ## Example Usage ```terraform # Only the attributes set here are managed; everything else stays as it is. resource "uptimeify_organization_settings" "this" { company_name = "Example GmbH" street = "Hauptstrasse 1" postal_code = "10115" city = "Berlin" country = "Germany" default_notification_channels = { email = true sms = false webhook = false integrations = true } } ``` ## Schema ### Optional - `billing_email` (String) Address for invoices (admins only). Unset = keep the current value. - `city` (String) Billing address. Unset = keep the current value. - `company_name` (String) Company name on invoices. Unset = keep the current value. - `country` (String) Billing country (free text; the server derives the ISO code). Changing it resets the VAT check. Unset = keep the current value. - `default_notification_channels` (Attributes) Channels switched on for new customers. Unset = keep. (see [below for nested schema](#nested-schema-for-default_notification_channels)) - `default_notification_targets` (Attributes) Who receives each channel for new customers: `customer`, `organization` or `both` (`webhook`: `organization` only). Unset = keep. (see [below for nested schema](#nested-schema-for-default_notification_targets)) - `name` (String) Organization name. Unset = keep the current value. - `postal_code` (String) Billing address. Unset = keep the current value. - `require_mfa_admins` (Boolean) Require two-step verification for admins. Changing it needs a signed-in admin who has two-step verification: API tokens are refused (`nonUserSessionForbidden`). An unchanged value is never sent. Unset = keep. - `require_mfa_customers` (Boolean) Require two-step verification for customer users (logins limited to customers). Changing it needs a signed-in admin who has two-step verification: API tokens are refused (`nonUserSessionForbidden`). An unchanged value is never sent. Unset = keep. - `require_mfa_editors` (Boolean) Require two-step verification for team editors. Changing it needs a signed-in admin who has two-step verification: API tokens are refused (`nonUserSessionForbidden`). An unchanged value is never sent. Unset = keep. - `require_mfa_readonly` (Boolean) Require two-step verification for team readonly members. Changing it needs a signed-in admin who has two-step verification: API tokens are refused (`nonUserSessionForbidden`). An unchanged value is never sent. Unset = keep. - `sms_overage_safety_cap_cents_monthly` (Number) Monthly SMS overage cap in cents. Only global admins may change it (`forbidden` for organization tokens); an unchanged value is never sent. Clearing it (null) is not possible here. Unset = keep. - `street` (String) Billing address. Unset = keep the current value. - `vat_id` (String) VAT ID. Changing it resets the VIES verdict until it is validated again. Unset = keep the current value. ### Read-Only - `id` (String) The organization id. ### Nested Schema for `default_notification_channels` Required: - `email` (Boolean) - `integrations` (Boolean) - `sms` (Boolean) - `webhook` (Boolean) ### Nested Schema for `default_notification_targets` Required: - `email` (String) - `integrations` (String) - `sms` (String) - `webhook` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Any id; the token's own organization is used terraform import uptimeify_organization_settings.this org ``` ### uptimeify_package_config URL: https://docs.uptimeify.io/terraform/resources/package_config Description: One package of the organization, addressed by its package_type (PATCH /api/package-configs/{packageType}). Manages the limits only: monitors, status pages and self-service per customer of the package. The check and alert defaults of the package stay as they are (the server's defaults for a new package); read them with data.uptimeify_package_configs. Its enable_*_alerts switches govern only the organization's notifications about the package's customers (organization channels and the organization recipient of the email/SMS fallback), never channels a customer created in their own account; a customer's own enable_*_alerts value replaces them for that customer. SMS through a customer's own channels still counts against the package's monthly SMS limit per customer and the organization's overage limit (0 while the package SMS switch is off and no limit is set). If the package already exists, creating the resource adopts it. Destroy deletes the package and fails (packageInUse) while customers use it. Import with the package type. Summary: One package of the organization, addressed by its `package_type` (`PATCH /api/package-configs/{packageType}`). Manages the limits only: monitors, status pages and self-service per customer of the package. The check and alert defaults of the package stay as they are (the server's defaults for a new package); read them with `data.uptimeify_package_configs`. Its `enable_*_alerts` switches govern only the organization's notifications about the package's customers (organization channels and the organization recipient of the email/SMS fallback), never channels a customer created in their own account; a customer's own `enable_*_alerts` value replaces them for that customer. SMS through a customer's own channels still counts against the package's monthly SMS limit per customer and the organization's overage limit (0 while the package SMS switch is off and no limit is set). If the package already exists, creating the resource adopts it. Destroy deletes the package and fails (`packageInUse`) while customers use it. Import with the package type. ## Example Usage ```terraform resource "uptimeify_package_config" "business" { package_type = "business" display_name = "Business" max_urls = 50 max_status_pages = 3 # unset = unlimited allow_self_service = true } ``` ## Schema ### Required - `package_type` (String) Package key, 1 to 64 characters, no surrounding whitespace, e.g. `essential`. Changing it replaces the package. ### Optional - `allow_self_service` (Boolean) Customers of the package may create their own (`self_service`) monitors and status pages. Unset = kept as is. - `display_name` (String) Name shown in the UI, 1 to 64 characters. Unset = kept as is. - `max_self_service_urls` (Number) Self-service monitors per customer. Unset = kept as is. - `max_status_pages` (Number) Status pages per customer of this package. Unset = unlimited. Pages without a customer never count. - `max_urls` (Number) Monitors per customer. Unset = kept as is (a new package uses the default of its type). - `notes` (String) Internal notes, up to 4096 characters. Unset = kept as is (the API cannot clear them). ### Read-Only - `id` (String) Same as `package_type`. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Package type terraform import uptimeify_package_config.business business ``` ### uptimeify_report URL: https://docs.uptimeify.io/terraform/resources/report Description: A scheduled fleet report of the organization (mail, optionally with PDF). Unset optional attributes take the server default on create and keep their value afterwards. Import with the report id (UUID). Summary: A scheduled fleet report of the organization (mail, optionally with PDF). Unset optional attributes take the server default on create and keep their value afterwards. Import with the report id (UUID). ## Example Usage ```terraform resource "uptimeify_report" "weekly" { name = "Weekly fleet report" frequency = "weekly" weekday = 1 send_hour = 7 format = "email_pdf" recipient_emails = ["ops@example.com"] # The status pages section is on by default; leave it out of this report. include_status_pages = false } ``` ## Schema ### Required - `name` (String) ### Optional - `day_of_month` (Number) 1-28. Required for monthly reports. - `enabled` (Boolean) Default `true`. - `format` (String) `email` or `email_pdf` (default). - `frequency` (String) `daily`, `weekly` or `monthly` (default). Weekly needs `weekday`, monthly needs `day_of_month`. - `group_by_customer` (Boolean) Group by customer. Default `false`. - `include_status_pages` (Boolean) Append the status pages section (published state, customer, components, incidents, maintenance, subscribers). Scope `customers` lists those customers' pages, scope `tags` the pages showing a monitor with one of the tags. Default `true`. - `inclusion_mode` (String) `all` (default), `problems` or `threshold`. - `monitor_types` (List of String) Monitor types in the report (default: all ten). - `problem_signals` (Attributes) What counts as a problem for `inclusion_mode = "problems"`. (see [below for nested schema](#nested-schema-for-problem_signals)) - `recipient_emails` (List of String) - `recipient_user_ids` (List of String) Logins of the organization (`uptimeify_user.id`). - `scope_customer_ids` (List of Number) Customers for `scope_mode = "customers"`. - `scope_mode` (String) `all` (default), `customers` or `tags`. - `scope_tag_ids` (List of Number) Tags for `scope_mode = "tags"`. - `sections` (Attributes) Report sections (default: all on except `group_by_customer`). (see [below for nested schema](#nested-schema-for-sections)) - `sections_by_type` (Map of Map of Boolean) Per monitor type section switches, e.g. `{ website = { sslExpiry = false } }` (server-side key names). - `send_hour` (Number) Hour of day 0-23 in `timezone`. Default 2. - `send_when_empty` (Boolean) Send even when nothing qualifies. Default `false`. - `threshold_response_gt` (Number) Response time in ms for `inclusion_mode = "threshold"`. - `threshold_uptime_lt` (Number) Uptime percentage for `inclusion_mode = "threshold"`. - `timezone` (String) IANA time zone. Default `Europe/Berlin`. - `weekday` (Number) 0-6, 0 = Sunday. Required for weekly reports. ### Read-Only - `created_at` (String) - `id` (String) Report id (UUID). ### Nested Schema for `problem_signals` Required: - `incident` (Boolean) - `response_breach` (Boolean) Optional: - `downtime_minutes` (Number) - `ssl_days_lt` (Number) ### Nested Schema for `sections` Required: - `fleet_summary` (Boolean) - `group_by_customer` (Boolean) - `incident_log` (Boolean) - `per_site_table` (Boolean) - `ssl_expiry` (Boolean) - `worst_performers` (Boolean) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Report id (UUID) terraform import uptimeify_report.weekly 0b5f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b ``` ### uptimeify_smtp_monitor URL: https://docs.uptimeify.io/terraform/resources/smtp_monitor Description: An SMTP monitor: connects and authenticates (check_mode protocol) or only checks the port (tcp). The hostname must resolve to a public address. Import with the numeric id or the public id. Summary: An SMTP monitor: connects and authenticates (check_mode `protocol`) or only checks the port (`tcp`). The hostname must resolve to a public address. Import with the numeric id or the public id. ## Example Usage ```terraform variable "smtp_password" { type = string sensitive = true } resource "uptimeify_smtp_monitor" "this" { customer_id = 12 name = "Outgoing mail" hostname = "mail.shop.example" port = 587 auth_user = "monitor@shop.example" # Write-only: never stored in state. Bump the version to send a new password. auth_pass_wo = var.smtp_password auth_pass_wo_version = 1 } ``` ## Schema ### Required - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `name` (String) Display name, 1 to 255 characters. ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `allow_duplicate` (Boolean, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Create the monitor even if the customer already has one of this type for the same target. Without it the create fails with 409 `monitorAlreadyExists` and the error names the import command for the existing monitor. Sent with create only. - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `auth_pass_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) SMTP password. Required in check_mode `protocol`. Write-only (Terraform 1.11+ / OpenTofu 1.11+), never stored in state or returned by the API; sent on create and whenever the matching `*_wo_version` changes. - `auth_pass_wo_version` (Number) Change this number to send `auth_pass_wo` again. - `auth_user` (String) SMTP user. Required in check_mode `protocol`. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `check_mode` (String) `protocol` (full login check, credentials required) or `tcp` (port reachability only; the API then stores no protocol settings and no credentials). Defaults to `protocol`. - `ignore_tls` (Boolean) Do not upgrade with STARTTLS. Defaults to false. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `port` (Number) TCP port. Unset = 465 with `secure`, else 25. - `require_tls` (Boolean) Fail without STARTTLS. Defaults to false. - `secure` (Boolean) Implicit TLS (SMTPS). Defaults to false. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. ### Read-Only - `created_at` (String) - `id` (String) Numeric SMTP monitor id. - `organization_id` (Number) - `public_id` (String) Public UUID of the SMTP monitor. - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id terraform import uptimeify_smtp_monitor.this 42 ``` ### uptimeify_smtp_settings URL: https://docs.uptimeify.io/terraform/resources/smtp_settings Description: The organization's own SMTP server for outgoing mail (one per organization). Destroying it switches back to platform sending (disable). The host must resolve to a public address. Organization admins only. Import with any id, e.g. smtp; the password is not imported. Summary: The organization's own SMTP server for outgoing mail (one per organization). Destroying it switches back to platform sending (`disable`). The host must resolve to a public address. Organization admins only. Import with any id, e.g. `smtp`; the password is not imported. ## Example Usage ```terraform variable "smtp_password" { type = string sensitive = true ephemeral = true } resource "uptimeify_smtp_settings" "this" { host = "smtp.example.com" port = 587 username = "alerts@example.com" password_wo = var.smtp_password password_wo_version = 1 # bump to send a new password tls_mode = "starttls" from_name = "Example Monitoring" from_email = "alerts@example.com" } ``` ## Schema ### Required > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `from_email` (String) - `host` (String) - `password_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only SMTP password, never stored in the state or returned. Sent on create and whenever `password_wo_version` changes. - `port` (Number) - `username` (String) ### Optional - `from_name` (String) - `password_wo_version` (Number) Change to resend `password_wo`. - `reply_to` (String) - `tls_mode` (String) `ssl`, `starttls` or `none`. ### Read-Only - `has_password` (Boolean) - `id` (String) The ID of this resource. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Any id; the password is not imported terraform import uptimeify_smtp_settings.this smtp ``` ### uptimeify_ssh_monitor URL: https://docs.uptimeify.io/terraform/resources/ssh_monitor Description: An SSH monitor: logs in (check_mode protocol) or only checks the port (tcp). The hostname must resolve to a public address. Import with the numeric id or the public id. Summary: An SSH monitor: logs in (check_mode `protocol`) or only checks the port (`tcp`). The hostname must resolve to a public address. Import with the numeric id or the public id. ## Example Usage ```terraform resource "uptimeify_ssh_monitor" "this" { customer_id = 12 name = "Bastion" hostname = "bastion.shop.example" username = "monitor" private_key_wo = file("~/.ssh/uptimeify_monitor") secrets_wo_version = 1 } # Port reachability only, no credentials. resource "uptimeify_ssh_monitor" "port_only" { customer_id = 12 name = "Bastion port" hostname = "bastion.shop.example" check_mode = "tcp" } ``` ## Schema ### Required - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `name` (String) Display name, 1 to 255 characters. ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `allow_duplicate` (Boolean, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Create the monitor even if the customer already has one of this type for the same target. Without it the create fails with 409 `monitorAlreadyExists` and the error names the import command for the existing monitor. Sent with create only. - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `check_mode` (String) `protocol` (full login check, credentials required) or `tcp` (port reachability only; the API then stores no protocol settings and no credentials). Defaults to `protocol`. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `passphrase_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Passphrase of the private key. Write-only (Terraform 1.11+ / OpenTofu 1.11+), never stored in state or returned by the API; sent on create and whenever the matching `*_wo_version` changes. - `password_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Login password; `password_wo` or `private_key_wo` is required in check_mode `protocol`. Write-only (Terraform 1.11+ / OpenTofu 1.11+), never stored in state or returned by the API; sent on create and whenever the matching `*_wo_version` changes. - `port` (Number) TCP port. Unset = 22. - `private_key_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Private key (OpenSSH/PEM). Write-only (Terraform 1.11+ / OpenTofu 1.11+), never stored in state or returned by the API; sent on create and whenever the matching `*_wo_version` changes. - `secrets_wo_version` (Number) Change this number to send `password_wo`, `private_key_wo` and `passphrase_wo` again. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. - `username` (String) Login user. Required in check_mode `protocol`. ### Read-Only - `created_at` (String) - `id` (String) Numeric SSH monitor id. - `organization_id` (Number) - `public_id` (String) Public UUID of the SSH monitor. - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id terraform import uptimeify_ssh_monitor.this 42 ``` ### uptimeify_sso_domain_verification URL: https://docs.uptimeify.io/terraform/resources/sso_domain_verification Description: Verifies the SSO domain's DNS TXT record once (POST /api/organization/sso/verify-domain). Create fails with the expected and the found TXT values when the record is not visible yet; publish uptimeify_sso_oidc.verification_record and apply again. There is no waiting or retrying. Needs an organization admin token. Set domain = uptimeify_sso_oidc..domain, so a new domain verifies again in the same apply. A new issuer also resets the verification: the next plan shows this resource again. Destroying it changes nothing in Uptimeify. Import with the id sso. Summary: Verifies the SSO domain's DNS TXT record once (`POST /api/organization/sso/verify-domain`). Create fails with the expected and the found TXT values when the record is not visible yet; publish `uptimeify_sso_oidc.verification_record` and apply again. There is no waiting or retrying. Needs an organization admin token. Set `domain = uptimeify_sso_oidc..domain`, so a new domain verifies again in the same apply. A new `issuer` also resets the verification: the next plan shows this resource again. Destroying it changes nothing in Uptimeify. Import with the id `sso`. ## Example Usage ```terraform # The TXT record from uptimeify_sso_oidc, published with your DNS provider. resource "dns_txt_record_set" "sso" { zone = "example.com." name = trimsuffix(uptimeify_sso_oidc.corp.verification_record.name, ".example.com") txt = [uptimeify_sso_oidc.corp.verification_record.value] ttl = 300 } # Verifies the TXT record once. Fails (no retry) while the record is not visible # yet; apply again after DNS has propagated. resource "uptimeify_sso_domain_verification" "corp" { domain = uptimeify_sso_oidc.corp.domain depends_on = [dns_txt_record_set.sso] } ``` ## Schema ### Required - `domain` (String) The SSO domain; changing it verifies again. ### Read-Only - `id` (String) Always `sso`. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Always the id sso terraform import uptimeify_sso_domain_verification.corp sso ``` ### uptimeify_sso_oidc URL: https://docs.uptimeify.io/terraform/resources/sso_oidc Description: Single sign-on of the organization with an OpenID Connect identity provider (PUT /api/organization/sso). One per organization; needs an organization admin token. Saving runs the issuer's discovery, so the issuer must be reachable over HTTPS from Uptimeify. Register the client at your identity provider with redirect_uri and the scopes (both known before the first apply, see GET /api/organization/sso). Prove the domain with the DNS TXT record verification_record and uptimeify_sso_domain_verification. A new domain or issuer resets the verification, the first login and enforce_sso. Destroying it removes SSO. A SAML configuration is not managed here: it reads as gone, and an apply replaces it with OIDC. Import with the id sso. Summary: Single sign-on of the organization with an OpenID Connect identity provider (`PUT /api/organization/sso`). One per organization; needs an organization admin token. Saving runs the issuer's discovery, so the issuer must be reachable over HTTPS from Uptimeify. Register the client at your identity provider with `redirect_uri` and the `scopes` (both known before the first apply, see `GET /api/organization/sso`). Prove the domain with the DNS TXT record `verification_record` and `uptimeify_sso_domain_verification`. A new `domain` or `issuer` resets the verification, the first login and `enforce_sso`. Destroying it removes SSO. A SAML configuration is not managed here: it reads as gone, and an apply replaces it with OIDC. Import with the id `sso`. ## Example Usage ```terraform variable "oidc_client_secret" { type = string sensitive = true } # Register the client at your identity provider first, with # uptimeify_sso_oidc.corp.redirect_uri and the scopes openid, email, profile. resource "uptimeify_sso_oidc" "corp" { issuer = "https://login.example.com/realms/corp" client_id = "uptimeify" client_secret_wo = var.oidc_client_secret client_secret_wo_version = 1 domain = "example.com" default_role = "editor" # enforce_sso = true # only after the domain is verified and one SSO login worked } ``` ## Schema ### Required - `client_id` (String) - `domain` (String) Lowercase email domain of the users who sign in with SSO, e.g. `example.com`. One organization per domain. - `issuer` (String) Issuer URL, `https://`, without trailing slash (the discovery document's `issuer` must match). ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `client_secret_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only client secret; required for the first save. Sent with create and whenever `client_secret_wo_version` changes; never stored in state. Removing it keeps the stored secret. - `client_secret_wo_version` (Number) Change to resend `client_secret_wo`. - `default_role` (String) Role of users created by their first SSO login: `readonly`, `editor`, `responder` or `admin`. Defaults to `readonly`. - `enforce_sso` (Boolean) Only SSO (no password login) for users of `domain`. Needs a verified domain and one completed SSO login (`can_enforce`), else the apply fails with 409 `ssoEnforceNotAllowed`. Defaults to `false`. ### Read-Only - `can_enforce` (Boolean) Whether `enforce_sso` may be switched on: domain verified and one SSO login done. - `domain_verified` (Boolean) Whether the TXT record was verified (see `uptimeify_sso_domain_verification`). - `id` (String) Always `sso`. - `redirect_uri` (String) Redirect (callback) URI to register at the identity provider. - `scopes` (List of String) Scopes Uptimeify requests at login (fixed: `openid`, `email`, `profile`). - `verification_record` (Attributes) DNS TXT record that proves control of `domain`; publish it with your DNS provider. (see [below for nested schema](#nested-schema-for-verification_record)) ### Nested Schema for `verification_record` Read-Only: - `name` (String) Name of the TXT record, `_uptimeify-sso.`. - `value` (String) Value of the TXT record. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Always the id sso (one SSO configuration per organization) terraform import uptimeify_sso_oidc.corp sso ``` ### uptimeify_status_page URL: https://docs.uptimeify.io/terraform/resources/status_page Description: A status page of one customer, or of the whole organization without customer_id. It shows its explicit components (uptimeify_status_page_component, the allowlist) and, only with include_customer_monitors, also every monitor of the customer except hidden_monitors. Design, audience groups, custom domain and IM rules are separate resources (uptimeify_status_page_design, uptimeify_status_page_audience_groups, uptimeify_status_page_domain, uptimeify_im_statuspage_rule). Deleting the page also deletes its custom domain. Import with the numeric id or the public id. Summary: A status page of one customer, or of the whole organization without `customer_id`. It shows its explicit components (`uptimeify_status_page_component`, the allowlist) and, only with `include_customer_monitors`, also every monitor of the customer except `hidden_monitors`. Design, audience groups, custom domain and IM rules are separate resources (`uptimeify_status_page_design`, `uptimeify_status_page_audience_groups`, `uptimeify_status_page_domain`, `uptimeify_im_statuspage_rule`). Deleting the page also deletes its custom domain. Import with the numeric id or the public id. ## Example Usage ```terraform data "uptimeify_customer" "acme" { name = "ACME GmbH" } # Shows the explicit components and every other monitor of the customer except the hidden ones. resource "uptimeify_status_page" "acme" { customer_id = tonumber(data.uptimeify_customer.acme.id) name = "ACME Status" slug = "acme" description = "Live status of the ACME shop." include_customer_monitors = true management_type = "self_service" # the customer operates it; default "managed" hidden_monitors = [ { type = "http", id = 1234 }, { type = "dns", id = 56 }, ] } # A page of the whole organization: no customer, only the explicit components # (uptimeify_status_page_component), which may come from any customer. Visitors may also # subscribe by SMS and browser push. sms_subscriptions_enabled = true needs SMS quota (included SMS # left or overage enabled), otherwise the apply fails with 403 smsQuotaRequired. resource "uptimeify_status_page" "platform" { name = "Platform Status" sms_subscriptions_enabled = true push_subscriptions_enabled = true } # Internal page: only members signed in through the organization's single sign-on, and only # from the office networks. Monitors do not write to it: it shows only what is reported # manually and incidents that are explicitly linked. resource "uptimeify_status_page" "staff" { name = "Staff Status" visibility = "sso_members_only" ip_allowlist = ["203.0.113.0/24", "2001:db8::/32"] monitor_updates_enabled = false } # Password-protected page; the password never lands in state. # Bump access_password_wo_version to send a new password. resource "uptimeify_status_page" "internal" { customer_id = tonumber(data.uptimeify_customer.acme.id) name = "ACME Internal" visibility = "password_protected" access_password_wo = var.status_page_password access_password_wo_version = 1 } variable "status_page_password" { type = string sensitive = true ephemeral = true } ``` ## Schema ### Required - `name` (String) 1 to 120 characters, no surrounding whitespace. ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `access_password_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Access password, 8 to 200 characters. Write-only: sent on create and whenever `access_password_wo_version` changes; never stored in state. Removing it does not remove the password. - `access_password_wo_version` (Number) Change to resend `access_password_wo`. - `customer_id` (Number) Customer the page belongs to. Unset = a page of the whole organization (organization-wide tokens and roles only); its components may then come from any customer. Changing or removing it moves the page in place; moving to a customer fails while the page has monitor components of another customer. - `description` (String) Up to 1000 characters, no surrounding whitespace. - `hidden_monitors` (Attributes Set) Monitors of the customer the page does not show, at most 500. Default: none (every monitor is shown). (see [below for nested schema](#nested-schema-for-hidden_monitors)) - `include_customer_monitors` (Boolean) Also show every monitor of the customer (minus `hidden_monitors`) after the explicit components (`uptimeify_status_page_component`). `false` = only the components. Unset = the server defaul… ### uptimeify_status_page_audience_groups URL: https://docs.uptimeify.io/terraform/resources/status_page_audience_groups Description: The audience groups of one status page (one resource per page): a component listed in a group is shown only to visitors signed in with a verified email address of one of the group's domains, and to editors of the page; components in no group stay visible to everyone who may view the page. A page with groups has no badge, widget, feeds or subscriptions. Destroying the resource removes all groups. Import with the numeric status page id. Summary: The audience groups of one status page (one resource per page): a component listed in a group is shown only to visitors signed in with a verified email address of one of the group's domains, and to editors of the page; components in no group stay visible to everyone who may view the page. A page with groups has no badge, widget, feeds or subscriptions. Destroying the resource removes all groups. Import with the numeric status page id. ## Example Usage ```terraform resource "uptimeify_status_page_component" "billing" { status_page_id = tonumber(uptimeify_status_page.acme.id) source_kind = "manual" name = "Billing backend" } # "Billing backend" is shown only to visitors signed in with a verified acme.com address # (and to editors of the page); every other component stays visible to all visitors. resource "uptimeify_status_page_audience_groups" "acme" { status_page_id = tonumber(uptimeify_status_page.acme.id) groups = [{ name = "ACME staff" email_domains = ["acme.com"] component_ids = [uptimeify_status_page_component.billing.component_id] }] } ``` ## Schema ### Required - `groups` (Attributes List) At most 20 groups, in this order; `[]` = none. (see [below for nested schema](#nested-schema-for-groups)) - `status_page_id` (Number) Numeric status page id. Changing it replaces the resource. ### Read-Only - `id` (String) Same as `status_page_id`. ### Nested Schema for `groups` Required: - `component_ids` (Set of Number) 1 to 100 numeric component ids of this page (`uptimeify_status_page_component..component_id`). - `email_domains` (Set of String) 1 to 20 domains, lowercase, e.g. `acme.com`; visitors with a verified email of one of them see the components. - `name` (String) 1 to 80 characters, no surrounding whitespace. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric status page id terraform import uptimeify_status_page_audience_groups.acme 42 ``` ### uptimeify_status_page_component URL: https://docs.uptimeify.io/terraform/resources/status_page_component Description: One component (row) of a status page: a monitor, a manually set status, or a third-party provider (dependency) whose published status it follows. At most 500 per page. Import with /. Summary: One component (row) of a status page: a monitor, a manually set status, or a third-party provider (`dependency`) whose published status it follows. At most 500 per page. Import with `/`. ## Example Usage ```terraform # A monitor of the page's customer resource "uptimeify_status_page_component" "shop" { status_page_id = tonumber(uptimeify_status_page.acme.id) source_kind = "monitor" monitor_type = "http" monitor_id = tonumber(uptimeify_website.shop.id) group_id = uptimeify_status_page_component_group.core.group_id } # A status you set yourself resource "uptimeify_status_page_component" "support" { status_page_id = tonumber(uptimeify_status_page.acme.id) source_kind = "manual" name = "Phone support" manual_status = "operational" } # A third-party provider; follows its published status resource "uptimeify_status_page_component" "github" { status_page_id = tonumber(uptimeify_status_page.acme.id) source_kind = "dependency" dependency_slug = "github" } ``` ## Schema ### Required - `source_kind` (String) `monitor`, `manual` or `dependency`. Changing it replaces the component. - `status_page_id` (Number) Numeric status page id. Changing it replaces the component. ### Optional - `dependency_slug` (String) With `source_kind = "dependency"`: provider slug from `GET /api/public/dependencies`, e.g. `github`. One component per provider and page. - `description` (String) Up to 1000 characters. - `group_id` (Number) Numeric id of an `uptimeify_status_page_component_group` of the same page. Unset = no group. - `manual_status` (String) With `source_kind = "manual"` only: `operational` (default), `degraded`, `partial_outage`, `major_outage` or `maintenance`. - `monitor_id` (Number) With `source_kind = "monitor"`: numeric monitor id, a monitor of the page's customer. One component per monitor and page. - `monitor_type` (String) With `source_kind = "monitor"`: `http` (website), `dns`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp` or `imap_pop`. - `name` (String) 1 to 120 characters. Required for `manual`; defaults to the monitor or provider name. - `show_uptime` (Boolean) Default `true`. - `sort` (Number) Position, ascending, 0 to 100000. Unset = after the last component at creation. ### Read-Only - `component_id` (Number) Numeric component id. - `created_at` (String) - `id` (String) `/`. - `public_id` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # / terraform import uptimeify_status_page_component.support 42/15 ``` ### uptimeify_status_page_component_group URL: https://docs.uptimeify.io/terraform/resources/status_page_component_group Description: A group of status page components (set group_id on uptimeify_status_page_component). Destroying a group keeps its components, ungrouped. Import with /. Summary: A group of status page components (set `group_id` on `uptimeify_status_page_component`). Destroying a group keeps its components, ungrouped. Import with `/`. ## Example Usage ```terraform resource "uptimeify_status_page_component_group" "core" { status_page_id = tonumber(uptimeify_status_page.acme.id) name = "Core services" sort = 0 } ``` ## Schema ### Required - `name` (String) 1 to 120 characters. - `status_page_id` (Number) Numeric status page id. Changing it replaces the group. ### Optional - `collapsed` (Boolean) Shown collapsed on the public page. Default `false`. - `sort` (Number) Position, ascending, 0 to 100000. Unset = after the last group at creation. ### Read-Only - `created_at` (String) - `group_id` (Number) Numeric group id. - `id` (String) `/`. - `public_id` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # / terraform import uptimeify_status_page_component_group.core 42/7 ``` ### uptimeify_status_page_design URL: https://docs.uptimeify.io/terraform/resources/status_page_design Description: The design of one status page (one per page). Unset arguments keep their current value; removing an argument from the configuration does not reset it. Destroying the resource resets the whole design to the defaults. Every option with examples: Status page design https://docs.uptimeify.io/status-pages/design. Import with the numeric status page id. Summary: The design of one status page (one per page). Unset arguments keep their current value; removing an argument from the configuration does not reset it. Destroying the resource resets the whole design to the defaults. Every option with examples: [Status page design](https://docs.uptimeify.io/status-pages/design). Import with the numeric status page id. ## Example Usage ```terraform resource "uptimeify_status_page_design" "acme" { status_page_id = tonumber(uptimeify_status_page.acme.id) layout = "statusboard" color_scheme = "auto" accent_color = "#0f766e" custom_title = "ACME Status" show_powered_by = false history_days = 90 incident_limit = 10 # Own texts for the states; states left out show the default text. status_labels = { operational = "All systems go" major_outage = "We are on it" } } ``` ## Schema ### Required - `status_page_id` (Number) Numeric status page id. Changing it replaces the resource. ### Optional - `accent_color` (String) 6-digit hex color, e.g. `#6366f1` (default). - `card_radius` (String) `none`, `md` (default) or `xl`. - `color_scheme` (String) `light`, `dark` or `auto` (default). - `custom_css` (String) Own CSS for the public page only, at most 20000 bytes; empty string = none (default). No `url()`, `@import`, `@font-face` or other resource loads; a rejected stylesheet fails the apply. Kept as written in state; the server's regenerated form is `custom_css_stored`. - `custom_subtitle` (String) Up to 200 characters. - `custom_title` (String) Visible page title, up to 120 characters. Empty = the page name. - `font_family` (String) `system` (default) or `mono`. - `header_style` (String) `simple` (default), `centered` or `hero`. - `history_days` (Number) Window of the availability bars, 1 to 3650 days. Default `30`. - `incident_days` (Number) 1 to 3650 days. Default `30`. - `incident_limit` (Number) 1 to 50 incidents. Default `5`. - `layout` (String) Layout preset, with its name and caption in the design editor: `classic` (Classic, card and list), `cards` (Cards, service grid), `minimal` (Minimal, clean lines), `sleek` (Sleek, dark with glow), `board` (Board, color rows), `split` (Split, two columns), `timeline` (Timeline, event feed), `compact` (Compact, dense table) or `statusboard` (Statusboard, uptime bars; the default). All show the same data. Descriptions and screenshots: [Status page design](https://docs.uptimeify.io/status-pages/design#layouts). - `maintenance_days` (Number) How far back past maintenance is shown, 1 to 3650 days. Default `30`. - `maintenance_limit` (Number) 1 to 50 maintenance windows. Default `5`. - `page_width` (String) `sm`, `md`, `lg` (default) or `xl`. - `show_history` (Boolean) Show availability bars. Default `true`. - `show_incidents` (Boolean) Default `true`. Same switch as `show_recent_incidents` of the page API. - `show_last_checked` (Boolean) Default `false`. - `show_maintenance` (Boolean) Default `true`. - `show_powered_by` (Boolean) Default `true`. - `show_service_urls` (Boolean) Show monitor URLs. Default `false`. - `show_uptime_stats` (Boolean) Default `true`. - `status_labels` (Map of String) Own public texts per state, used by every layout, the badge and the widget. Keys: `operational`, `degraded`, `partial_outage`, `major_outage`, `maintenance`; values 1 to 40 characters, no surrounding whitespace. When set, the map is the complete list: a state left out shows its default text. ### Read-Only - `custom_css_stored` (String) `custom_css` as the server stored it (regenerated and minified). A change made outside Terraform shows up here and in `custom_css`. - `id` (String) Same as `status_page_id`. - `seo_title` (String) `` override; not settable through the API. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric status page id terraform import uptimeify_status_page_design.acme 42 ``` ### uptimeify_status_page_domain URL: https://docs.uptimeify.io/terraform/resources/status_page_domain Description: A custom domain of a status page (at most one per page). Creating it registers the hostname as pending; nothing is verified or activated here. To go live: Publish the TXT record verification_record.name with the value verification_record.value in your DNS zone, and point the hostname (CNAME) at your Uptimeify status page host.Verify and activate: uptimeify_status_page_domain_activation (runs verify + activate once), or POST /api/status-pages/domains/verify and .../activate with {\"domainId\": <id>}. status is read from the API: pending, verified or active. Deleting the status page deletes its domain. Import with the numeric domain id. Summary: A custom domain of a status page (at most one per page). Creating it registers the hostname as `pending`; nothing is verified or activated here. To go live: 1. Publish the TXT record `verification_record.name` with the value `verification_record.value` in your DNS zone, and point the hostname (CNAME) at your Uptimeify status page host. 2. Verify and activate: `uptimeify_status_page_domain_activation` (runs verify + activate once), or `POST /api/status-pages/domains/verify` and `.../activate` with `{"domainId": <id>}`. `status` is read from the API: `pending`, `verified` or `active`. Deleting the status page deletes its domain. Import with the numeric domain id. ## Example Usage ```terraform resource "uptimeify_status_page_domain" "acme" { status_page_id = tonumber(uptimeify_status_page.acme.id) hostname = "status.acme.example" } # Publish this TXT record in your DNS zone (any DNS provider), e.g.: output "acme_status_txt" { value = uptimeify_status_page_domain.acme.verification_record } ``` ## Schema ### Required - `hostname` (String) Lowercase hostname, e.g. `status.example.com`. Changing it replaces the domain. - `status_page_id` (Number) Numeric status page id. Changing it replaces the domain. ### Read-Only - `created_at` (String) - `id` (String) Numeric domain id. - `last_verification_error` (String) JSON diagnosis of the last failed TXT verification (`recordName`, `expected`, `lookup`, `observed`, `nameservers`, `authoritative`, `propagation`), decode with `jsondecode()`; null when the last verification succeeded or none failed yet. - `last_verification_error_at` (String) When `last_verification_error` happened (RFC 3339). - `status` (String) `pending`, `verified` or `active`. - `verification_record` (Attributes) DNS TXT record that proves control of the hostname. (see [below for nested schema](#nested-schema-for-verification_record)) - `verified_at` (String) ### Nested Schema for `verification_record` Read-Only: - `name` (String) Name of the TXT record. - `value` (String) Value of the TXT record. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric domain id terraform import uptimeify_status_page_domain.acme 17 ``` ### uptimeify_status_page_domain_activation URL: https://docs.uptimeify.io/terraform/resources/status_page_domain_activation Description: Verifies a status page domain's DNS TXT record and activates the domain, once. Create fails with the API's answer when the TXT record is not visible yet; publish it (see uptimeify_status_page_domain) and apply again. There is no waiting or retrying. Needs an organization admin token. When the domain is no longer active (e.g. a later re-verification failed), the next plan runs verify + activate again. Destroying this resource does not deactivate the domain; destroy the uptimeify_status_page_domain for that. Import with the domain id. Summary: Verifies a status page domain's DNS TXT record and activates the domain, once. Create fails with the API's answer when the TXT record is not visible yet; publish it (see `uptimeify_status_page_domain`) and apply again. There is no waiting or retrying. Needs an organization admin token. When the domain is no longer `active` (e.g. a later re-verification failed), the next plan runs verify + activate again. Destroying this resource does not deactivate the domain; destroy the `uptimeify_status_page_domain` for that. Import with the domain id. ## Example Usage ```terraform # The TXT record from uptimeify_status_page_domain, published with your DNS provider. resource "dns_txt_record_set" "acme_status" { zone = "acme.example." name = trimsuffix(uptimeify_status_page_domain.acme.verification_record.name, ".acme.example") txt = [uptimeify_status_page_domain.acme.verification_record.value] ttl = 300 } # Verifies the TXT record and activates the domain once. Fails (no retry) while the # record is not visible yet; apply again after DNS has propagated. resource "uptimeify_status_page_domain_activation" "acme" { domain_id = tonumber(uptimeify_status_page_domain.acme.id) depends_on = [dns_txt_record_set.acme_status] } ``` ## Schema ### Required - `domain_id` (Number) `uptimeify_status_page_domain.<name>.id` as number. ### Read-Only - `id` (String) Same as `domain_id`. - `status` (String) `active` after a successful run. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric domain id terraform import uptimeify_status_page_domain_activation.acme 7 ``` ### uptimeify_status_page_maintenance URL: https://docs.uptimeify.io/terraform/resources/status_page_maintenance Description: A planned maintenance announced on one or more status pages, optionally for some of their components. It starts and ends by itself at scheduled_for/scheduled_until and notifies subscribers as configured; creating it announces it right away when notify_on_schedule is true. It does not silence monitor alerts (that is uptimeify_maintenance_window). Ending a running maintenance early and cancelling an upcoming one are lifecycle actions outside this resource (dashboard, API or MCP); a cancelled maintenance refuses further changes, so change the configuration only after removing or replacing it. Import with the numeric id or the public id. Summary: A planned maintenance announced on one or more status pages, optionally for some of their components. It starts and ends by itself at `scheduled_for`/`scheduled_until` and notifies subscribers as configured; creating it announces it right away when `notify_on_schedule` is true. It does not silence monitor alerts (that is `uptimeify_maintenance_window`). Ending a running maintenance early and cancelling an upcoming one are lifecycle actions outside this resource (dashboard, API or MCP); a cancelled maintenance refuses further changes, so change the configuration only after removing or replacing it. Import with the numeric id or the public id. ## Example Usage ```terraform resource "uptimeify_status_page_maintenance" "db_upgrade" { title = "Database upgrade" description = "The API is read-only for about 30 minutes." scheduled_for = "2026-11-03T22:00:00+01:00" scheduled_until = "2026-11-03T23:00:00+01:00" status_page_ids = [tonumber(uptimeify_status_page.main.id)] # Only these components show the maintenance; leave out for the whole page. component_ids = [uptimeify_status_page_component.api.component_id] reminder_minutes_before = 60 notify_on_start = true } ``` ## Schema ### Required - `scheduled_for` (String) Start, RFC 3339 with offset. The configured spelling is kept while the instant is unchanged. - `scheduled_until` (String) End, RFC 3339 with offset, after `scheduled_for`. - `status_page_ids` (Set of Number) Numeric ids of the status pages that show the maintenance, 1 to 10. - `title` (String) Public headline, 1 to 200 characters. ### Optional - `component_ids` (Set of Number) Numeric ids of affected components (`component_id` of `uptimeify_status_page_component`), each on one of the pages. Unset: the whole page. - `description` (String) What happens and what visitors notice, up to 5000 characters. - `notify_on_complete` (Boolean) Notify subscribers when it ends. Default `true`. - `notify_on_schedule` (Boolean) Announce to subscribers when saved and again when the start moves. Default `true`. - `notify_on_start` (Boolean) Notify subscribers when it begins. Default `false`. - `reminder_minutes_before` (Number) Remind subscribers this many minutes before the start, 5 to 10080. Unset: no reminder. ### Read-Only - `cancelled_at` (String) When it was cancelled, if it was. - `id` (String) Numeric maintenance id. - `public_id` (String) - `state` (String) `scheduled`, `in_progress`, `completed` or `cancelled`, derived from the clock at the last read. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id of the maintenance. terraform import uptimeify_status_page_maintenance.db_upgrade 42 ``` ### uptimeify_tag URL: https://docs.uptimeify.io/terraform/resources/tag Description: A tag that groups monitors. Import with the numeric id or the public id. Summary: A tag that groups monitors. Import with the numeric id or the public id. ## Example Usage ```terraform resource "uptimeify_tag" "production" { name = "production" color = "red" } # Scoped to one customer instead of the whole organization. resource "uptimeify_tag" "customer" { name = "eu-shop" customer_id = 12 } ``` ## Schema ### Required - `name` (String) Tag name, 1 to 24 characters. ### Optional - `color` (String) Palette key: `slate`, `red`, `amber`, `green`, `teal`, `blue`, `indigo`, `violet`, `pink`, `gray`. Defaults to `slate`. - `customer_id` (Number) Scope the tag to this customer. Unset = organization-wide. Customer tokens must set it. ### Read-Only - `created_at` (String) - `id` (String) Numeric tag id. - `public_id` (String) Public UUID of the tag. - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id terraform import uptimeify_tag.production 42 ``` ### uptimeify_tcp_monitor URL: https://docs.uptimeify.io/terraform/resources/tcp_monitor Description: A TCP monitor: connects to hostname:port, optionally expecting a banner. The hostname must resolve to a public address when it is set. Import with the numeric id or the public id. Summary: A TCP monitor: connects to `hostname`:`port`, optionally expecting a banner. The hostname must resolve to a public address when it is set. Import with the numeric id or the public id. ## Example Usage ```terraform resource "uptimeify_tcp_monitor" "this" { customer_id = 12 name = "Postgres primary" hostname = "db.shop.example" port = 5432 check_interval = 5 } # Inverted: alert when the Redis port is reachable from the internet. resource "uptimeify_tcp_monitor" "redis_closed" { customer_id = 12 name = "Redis not exposed" hostname = "cache.shop.example" port = 6379 expected_state = "down" } ``` ## Schema ### Required - `customer_id` (Number) Customer the monitor belongs to. Changing it moves the monitor to another customer of the same organization in place. - `hostname` (String) Host name or IP address only: no scheme, no path, no spaces. - `name` (String) Display name, 1 to 255 characters. - `port` (Number) ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `allow_duplicate` (Boolean, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Create the monitor even if the customer already has one of this type for the same target. Without it the create fails with 409 `monitorAlreadyExists` and the error names the import command for the existing monitor. Sent with create only. - `allowed_check_country_codes` (Set of String) Upper-case ISO 3166-1 alpha-2 codes of the allowed check locations. Unset = all locations. - `check_interval` (Number) Minutes between checks, 1 to 1440. Defaults to 30. The customer's package can require a larger minimum. - `expect_banner` (String) Text the server's greeting must contain, at most 255 characters. - `expected_state` (String) `up` (default) alerts when the port is not reachable. `down` inverts the monitor: an open connection is an outage; refused, timeout, reset and unreachable count as OK. A DNS failure stays an outage. - `management_type` (String) `managed` or `self_service`. Only organization writers choose it; customer tokens always get `self_service`. Defaults to `managed`. - `status` (String) `active`, `maintenance` or `disabled`. Defaults to `active`. - `timeout_seconds` (Number) Timeout per check in seconds, 1 to 60. Defaults to 30. ### Read-Only - `created_at` (String) - `id` (String) Numeric TCP monitor id. - `organization_id` (Number) - `public_id` (String) Public UUID of the TCP monitor. - `updated_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric id or public id terraform import uptimeify_tcp_monitor.this 42 ``` ### uptimeify_user URL: https://docs.uptimeify.io/terraform/resources/user Description: A login of the organization. Creating it sends an invitation mail; the person sets their own password (Terraform never sets one). Destroying it deletes the login. Needs an organization admin token. Import with the user id. Summary: A login of the organization. Creating it sends an invitation mail; the person sets their own password (Terraform never sets one). Destroying it deletes the login. Needs an organization admin token. Import with the user id. ## Example Usage ```terraform # Sends an invitation mail; the person sets their own password. resource "uptimeify_user" "ops" { email = "ops@example.com" first_name = "Olivia" last_name = "Ops" role = "editor" } # A customer login, limited to one customer. resource "uptimeify_user" "shop_owner" { email = "owner@shop.example" role = "readonly" customer_ids = [12] language = "en" } ``` ## Schema ### Required - `email` (String) Login address. Changing it invites a new login (replacement). - `role` (String) `admin`, `editor`, `readonly` or `responder`. ### Optional - `customer_ids` (Set of Number) Customers a `readonly` login is limited to (customer user). Empty = all customers. Only allowed with `role = "readonly"`. - `first_name` (String) - `is_active` (Boolean) `false` deactivates the login without deleting it. - `language` (String) Language of the login (dashboard, mails, SMS): `de`, `en` or `da`; null = organization language. Always read from the API, so a language the person picks in their profile shows as drift. A change is sent in place (PATCH); removing it from the configuration keeps the current language. - `last_name` (String) ### Read-Only - `created_at` (String) - `id` (String) User id, as `user_id` in IM resources. - `name` (String) Display name the server derives from first and last name. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # User id terraform import uptimeify_user.ops 3f1c0a8e-... ``` ### uptimeify_user_notification_settings URL: https://docs.uptimeify.io/terraform/resources/user_notification_settings Description: Personal Incident Management notification settings of one user of the organization, set by an organization admin (PUT /api/im/users/{userId}/notification-settings). The last write wins: the user can change them afterwards, which shows up as drift. Destroying only removes them from the state, the user keeps the chain. Import with the user id. Summary: Personal Incident Management notification settings of one user of the organization, set by an organization admin (`PUT /api/im/users/{userId}/notification-settings`). The last write wins: the user can change them afterwards, which shows up as drift. Destroying only removes them from the state, the user keeps the chain. Import with the user id. ## Example Usage ```terraform # An org admin sets up how a responder is paged. SMS and voice steps wait until the # responder confirms the number (they are asked to on their next sign-in). data "uptimeify_user" "rita" { email = "rita@example.com" } resource "uptimeify_user_notification_settings" "rita" { user_id = data.uptimeify_user.rita.id phone_number = "+491701234567" rules = [ { urgency = "high", delay_minutes = 0, channel = "push" }, { urgency = "high", delay_minutes = 5, channel = "sms" }, { urgency = "high", delay_minutes = 15, channel = "voice" }, { urgency = "low", delay_minutes = 0, channel = "email" }, ] } ``` ## Schema ### Required - `rules` (Attributes Set) The whole notification chain; replaces every existing rule of the user. (see [below for nested schema](#nested-schema-for-rules)) - `user_id` (String) User of this organization with role admin, editor or responder. ### Optional - `channels` (Map of Boolean) Delivery switches `push`, `sms`, `voice`, `email`. Unset = on exactly for the channels the rules use. - `phone_number` (String) E.164 number, e.g. `+491701234567`. Unset = keep the user's number. A new number is unverified until the user confirms the SMS code. ### Read-Only - `id` (String) The user id. - `phone_verified` (Boolean) Whether the user confirmed the number. Until then `sms` and `voice` steps are skipped. ### Nested Schema for `rules` Required: - `channel` (String) `push`, `sms`, `voice` or `email`. `sms` and `voice` wait until the phone number is verified. - `delay_minutes` (Number) Minutes after the page starts, 0 to 1440. - `urgency` (String) `high` or `low`. ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # The import id is the user id. terraform import uptimeify_user_notification_settings.rita usr_8f2c ``` ### uptimeify_website URL: https://docs.uptimeify.io/terraform/resources/website Description: A website monitor: HTTP(S) check (combined, http_status, ssl_check) or heartbeat (heartbeat, the monitored system pings Uptimeify). Import with the numeric id or the public id. Updates use the partial mode of PATCH /api/websites/{id} whenever every changed field is one that mode accepts (name, url, status, interval, timeout, checks, keyword, expected response, connect target, SSL/domain days, page sizes, grace period). Changes to the customer, countries, HTTP method, redirects, cookies, auth or the write-only secrets need the full mode, which resets omitted fields to defaults, so the provider then sends every attribute and re-applies any value the full mode coerced (ssl_error_days = 0, min_page_size = 0) with a partial PATCH. Secrets (custom headers, request body, authorization header, basic auth password) are write-only: the API never returns them. Bump the matching *_wo_version to send changed values. Summary: A website monitor: HTTP(S) check (`combined`, `http_status`, `ssl_check`) or heartbeat (`heartbeat`, the monitored system pings Uptimeify). Import with the numeric id or the public id. Updates use the partial mode of `PATCH /api/websites/{id}` whenever every changed field is one that mode accepts (name, url, status, interval, timeout, checks, keyword, expected response, connect target, SSL/domain days, page sizes, grace period). Changes to the customer, countries, HTTP method, redirects, cookies, auth or the write-only secrets need the full mode, which resets omitted fields to defaults, so the provider then sends every attribute and re-applies any value the full mode coerced (`ssl_error_days = 0`, `min_page_size = 0`) with a partial PATCH. Secrets (custom headers, request body, authorization header, basic auth password) are write-only: the API never returns them. Bump the matching `*_wo_version` to send changed values. ## Example Usage ```terraform data "uptimeify_customer" "shop" { name = "Example Shop GmbH" } variable "api_key" { type = string sensitive = true } # HTTP check with request headers, body, content checks and a connect target. resource "uptimeify_website" "api" { customer_id = tonumber(data.uptimeify_customer.shop.id) name = "Shop API health" url = "https://shop.example.com/api/health" http_method = "POST" check_interval = 5 timeout_seconds = 10 expected_status_codes = "200" check_keyword_enabled = true search_term = "\"status\":\"ok\"" allowed_check_country_codes = ["DE", "NL"] # Check the origin directly; SNI and Host header stay shop.example.com. connect_host = "origin.example.com" connect_port = 8443 # Write-only: never stored in state, never returned by the API. # Bump the version to send changed values. custom_headers_wo = [ { name = "X-Api-Key", value = var.api_key }, { name = "Accept", value = "application/json" }, ] custom_headers_wo_version = 1 request_body_wo = jsonencode({ probe = true }) request_body_wo_version = 1 } # Heartbeat: the monitored job calls the ping URL with heartbeat_token. resource "uptimeify_website" "nightly_backup" { customer_id = tonumber(data.uptimeify_customer.shop.id) name = "Nightly backup" monitoring_type = "heartbeat" check_interval = 1440 heartbeat_grace_period_minutes = 60 # Change to any new value to mint a new token. The old token stops working # immediately, so roll out the new ping URL in the same change. heartbeat_token_rotation = "2026-10" } # Inverted heartbeat: a ping is an outage (e.g. a failover script that must # never fire); silence beyond interval + grace counts as OK. resource "uptimeify_website" "failover_never_runs" { customer_id = tonumber(data.uptimeify_customer.shop.id) name = "Failover not triggered" monitoring_type = "heartbeat" check_interval = 60 heartbeat_grace_period_minutes = 5 expected_state = "down" } ``` ## Schema ### Required - `customer_id` (Number) Numeric id of the customer that owns the monitor. Changing it moves the monitor. - `name` (String) ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - `allow_duplicate` (Boolean, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Create the monitor even if the customer already has one of this type for the same target. Without it the create fails with 409 `monitorAlreadyExists` and the error names the import command for the existing monitor. Sent with create only. - `allowed_check_country_codes` (Set of String) Upper-case ISO country codes of the check locations. Unset at create: the package default (null = all). Removing it later keeps the last value. - `auth_mode` (String) `none`, `authorization_header` (needs `authorization_header_wo`) or `basic` (needs `basic_auth_username` and `basic_auth_password_wo`). Defaults to `none`. - `auth_wo_version` (Number) Change to resend the auth secrets. - `authorization_heade… ### uptimeify_whitelabel_domain URL: https://docs.uptimeify.io/terraform/resources/whitelabel_domain Description: A custom app domain (white label) of the organization. Terraform creates it as pending and outputs the DNS TXT record that proves control. Verifying and activating are one-off actions, not managed here: POST /api/organization/whitelabel/domains/verify with { \"domainId\": <id> } once the record is live, then POST /api/organization/whitelabel/domains/activate (optionally makePrimary). Organization admins only. Import with the numeric id. Summary: A custom app domain (white label) of the organization. Terraform creates it as `pending` and outputs the DNS TXT record that proves control. Verifying and activating are one-off actions, not managed here: `POST /api/organization/whitelabel/domains/verify` with `{ "domainId": <id> }` once the record is live, then `POST /api/organization/whitelabel/domains/activate` (optionally `makePrimary`). Organization admins only. Import with the numeric id. ## Example Usage ```terraform resource "uptimeify_whitelabel_domain" "app" { hostname = "monitoring.example.com" } # Publish this TXT record, then verify once: # POST /api/organization/whitelabel/domains/verify { "domainId": <id> } output "txt_record" { value = "${uptimeify_whitelabel_domain.app.dns_txt_name} TXT ${uptimeify_whitelabel_domain.app.dns_txt_value}" } ``` ## Schema ### Required - `hostname` (String) Hostname, e.g. `status.example.com`. No wildcards, no platform hostnames. ### Read-Only - `created_at` (String) - `dns_txt_name` (String) Name of the TXT record to publish. - `dns_txt_value` (String) Value of the TXT record. - `id` (String) Numeric domain id (`domainId`). - `is_primary` (Boolean) The first app domain becomes primary. - `last_verification_error` (String) JSON diagnosis of the last failed TXT verification (`recordName`, `expected`, `lookup`, `observed`, `nameservers`, `authoritative`, `propagation`), decode with `jsondecode()`; null when the last verification succeeded or none failed yet. - `last_verification_error_at` (String) When `last_verification_error` happened (RFC 3339). - `status` (String) `pending`, `verified` or `active`. - `verified_at` (String) ## Import Import is supported using the following syntax: The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example: ```shell # Numeric domain id terraform import uptimeify_whitelabel_domain.app 7 ``` ### Secrets and updates URL: https://docs.uptimeify.io/terraform/secrets-and-updates Description: How the Uptimeify provider keeps secrets out of state, how package limits show up in plan and apply, and how updates reach the API. Summary: ## Secrets stay out of your state Every secret is a write-only attribute ending in `_wo`: custom request headers, request bodies, authorization headers, basic auth passwords, webhook secrets and HMAC keys. OpenTofu and Terraform never store them in state, and the API never returns them. Because the provider cannot read a write-only value back, it sends it only when the matching `*_wo_version` changes. To rotate a secret, change the value **and** increase the version: ```terraform resource "uptimeify_website" "api" { # ... custom_headers_wo = [ { name = "X-Api-Key", value = var.api_key }, ] custom_headers_wo_version = 2 # was 1: sends the new header } ``` Attributes like `has_custom_headers` show whether a secret is set, without revealing it. ## Package limits Some checks depend on the customer's package, for example the keyword or page size check. If you switch on a check the package does not include, `apply` fails with `checkNotInPackage` instead of silently storing `false`. [`uptimeify_package_configs`](/terraform/data-sources/package_configs) shows what each package allows. A check without its companion value measures nothing. If you remove `search_term`, also remove or disable `check_keyword_enabled`. When the configuration leaves the switch out, the provider plans it off in the same update. ## How updates reach the API Most changes go out as a partial update that touches only the changed fields. A few fields (for website monitors: customer, check countries, HTTP method, redirects, cookies, auth and the write-only secrets) need the API's full update. The provider then sends every attribute, so nothing you did not change is reset. Details are on the resource page, for example [`uptimeify_website`](/terraform/resources/website). ## Drift Changes made in the dashboard show up in the next `plan` and are reset on `apply`. Server-generated values (ids, heartbeat tokens, timestamps) are read-only and never cause drift.