API reference
The ZeroDrop control plane is a JSON HTTP API. It's OpenAPI-first: api/openapi.yaml is the source of truth, and this page is generated from it.
Base URL
In production the API is served under /api, so every path below is prefixed with it, e.g. POST /api/v1/http-checks. The paths shown here are as the backend sees them (/v1/...).
Authentication
Two schemes are accepted:
- Bearer token: send
Authorization: Bearer <token> from scripts and automation. Create tokens on the API tokens page (see the user guide). This is the right choice for anything non-interactive, and bearer requests are exempt from CSRF.
- Session cookie (
zd_session): set by the browser sign-in flow and used by the console. Cookie-authenticated mutations must carry a matching Origin.
Endpoints marked Public need no authentication.
Conventions
- Request and response bodies are
application/json.
- Errors use a consistent shape: an
Error object with a single human-readable, actionable error string, plus the matching HTTP status.
- Mutating requests are rate-limited per organisation; exceeding the limit returns
429 with a Retry-After header (seconds) saying how long to back off. Reads are not throttled.
- Any mutating request can carry an
Idempotency-Key header to make it safe to retry, e.g. after a network timeout. A retry with the same key and the same method, path and body replays the original response (marked with an Idempotency-Replayed: true response header) instead of running again, which is what makes it safe to retry a create even for resources with no natural uniqueness constraint, such as notification channels, status pages and maintenance windows. Reusing a key for a different request returns 422; a concurrent retry still in flight returns 409. The header is optional: omitting it is unchanged from before it existed, so a retry may duplicate. Keys are retained for 24h.
Managing checks as code
PUT /v1/tenants/{org}/checks reconciles your entire set of checks against the request body in one transaction: checks are created or updated by name, and any check absent from the body is deleted. Keep the desired set in version control and apply it idempotently.
Authentication
POST
/v1/auth/signup
Public
Create an account
Request body: JSON (Credentials)
Responses
| Status | Description | Body |
|---|
201 | Account created (no session is started) | |
400 | Error | Error |
403 | Error | Error |
409 | Error | Error |
422 | Error | Error |
POST
/v1/auth/login
Public
Sign in with email and password
If the account has no second factor, returns 204 and sets the session cookie. If two-factor authentication is on, returns 200 with {"totp_required": true} and sets a short-lived pending cookie. Complete the sign-in with POST /v1/auth/login/totp.
Request body: JSON (Credentials)
Responses
| Status | Description | Body |
|---|
200 | Password accepted. A TOTP code is required to finish | TOTPRequired |
204 | Signed in; sets the zd_session cookie | |
400 | Error | Error |
401 | Error | Error |
403 | Error | Error |
POST
/v1/auth/login/totp
Public
Complete a two-factor sign-in with a TOTP code
Request body: JSON (TOTPCode)
Responses
| Status | Description | Body |
|---|
204 | Signed in; sets the zd_session cookie | |
400 | Error | Error |
401 | Error | Error |
POST
/v1/auth/logout
Session or bearer token
Sign out and clear the session
Responses
| Status | Description | Body |
|---|
204 | Signed out; clears the zd_session cookie | |
GET
/v1/auth/config
Public
Public client configuration for the auth flows
Returns the settings that the SPA needs before sign-in. At present that is the Cloudflare Turnstile site key. The key is empty when Turnstile is off.
Responses
POST
/v1/auth/password/forgot
Public
Request a password-reset link
Always returns 204, even when the email address has no account. The response therefore never reveals which addresses have accounts.
Request body: JSON (object: email, turnstile_token)
Responses
| Status | Description | Body |
|---|
204 | Accepted | |
400 | Error | Error |
403 | Error | Error |
POST
/v1/auth/password/reset
Public
Set a new password using a reset token
Request body: JSON (object: token, password)
Responses
| Status | Description | Body |
|---|
204 | Password updated; existing sessions are invalidated | |
400 | Error | Error |
410 | Error | Error |
422 | Error | Error |
POST
/v1/auth/password/change
Session or bearer token
Change the signed-in user's password
Requires the current password, and then sets the new one. All other sessions become invalid. This session gets a new cookie.
Request body: JSON (object: current_password, new_password)
Responses
| Status | Description | Body |
|---|
204 | Password changed; session refreshed | |
400 | Error | Error |
401 | Error | Error |
409 | Error | Error |
422 | Error | Error |
POST
/v1/auth/password/setup
Session or bearer token
Email a password-setup link to the signed-in user
Some accounts sign in with OAuth or a passkey and have no local password. For those accounts, this endpoint emails a single-use reset link to the address of the account. The user then sets a first password through the normal reset flow. If the account already has a password, returns 409. Use the change-password endpoint instead.
Responses
| Status | Description | Body |
|---|
204 | Setup link emailed (if the account has no password) | |
401 | Error | Error |
409 | Error | Error |
429 | Error | Error |
POST
/v1/auth/email/verify
Public
Confirm an email address using a verification token
Consumes the single-use token from the confirmation link and marks the email address of the account as verified. This endpoint is public, because the user can be signed out when they open the link.
Request body: JSON (object: token)
Responses
| Status | Description | Body |
|---|
204 | Email verified | |
400 | Error | Error |
410 | Error | Error |
POST
/v1/auth/email/resend
Session or bearer token
Resend the signed-in user's verification email
Issues a new confirmation link and emails it to the authenticated user. Always returns 204. For an account that is already verified, the call does nothing. The send has a rate limit for each account.
Responses
| Status | Description | Body |
|---|
204 | Accepted | |
401 | Error | Error |
POST
/v1/early-access
Public
Unlock the pre-launch early-access gate
Validates the shared early-access password. On success, sets the zd_early_access cookie (HttpOnly, about 30 days). The edge proxy reads this cookie before it serves the marketing site and the console. Each attempt has a rate limit for each client IP. The endpoint exists only when the server has an early-access password. Without one, the site is fully open and this endpoint is absent.
Request body: JSON (object: password)
Responses
| Status | Description | Body |
|---|
204 | Accepted; sets the zd_early_access cookie | |
400 | Error | Error |
401 | Error | Error |
429 | Error | Error |
GET
/v1/auth/totp
Session or bearer token
Report whether two-factor authentication is enabled
Responses
| Status | Description | Body |
|---|
200 | OK | object: enabled |
401 | Error | Error |
POST
/v1/auth/totp/setup
Session or bearer token
Begin TOTP enrollment
Generates a pending secret and the otpauth:// URL for an authenticator app.
Responses
| Status | Description | Body |
|---|
200 | OK | object: secret, otpauth_url |
401 | Error | Error |
409 | Error | Error |
503 | Error | Error |
POST
/v1/auth/totp/enable
Session or bearer token
Confirm TOTP enrollment with a code
Request body: JSON (TOTPCode)
Responses
| Status | Description | Body |
|---|
204 | Two-factor authentication enabled | |
401 | Error | Error |
422 | Error | Error |
POST
/v1/auth/totp/disable
Session or bearer token
Disable TOTP after verifying a current code
Request body: JSON (TOTPCode)
Responses
| Status | Description | Body |
|---|
204 | Two-factor authentication disabled | |
401 | Error | Error |
422 | Error | Error |
GET
/v1/auth/passkey
Session or bearer token
List the current user's passkeys
Responses
DELETE
/v1/auth/passkey/{id}
Session or bearer token
Remove one of the current user's passkeys
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
204 | Passkey removed | |
401 | Error | Error |
404 | Error | Error |
Account
GET
/v1/api-tokens
Session or bearer token
List the org's API tokens
Responses
POST
/v1/api-tokens
Session or bearer token
Issue a new API token
This response is the only place that returns the raw token secret.
Request body: JSON (object: name)
Responses
DELETE
/v1/api-tokens/{id}
Session or bearer token
Revoke an API token
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
204 | Token revoked | |
401 | Error | Error |
404 | Error | Error |
GET
/v1/me
Session or bearer token
Get the authenticated identity
Responses
| Status | Description | Body |
|---|
200 | OK | object: user_id, org_id, email, email_verified, has_password |
401 | Error | Error |
GET
/v1/settings
Session or bearer token
Get the org's settings
Responses
PUT
/v1/settings
Session or bearer token
Update the org's settings
Request body: JSON (SettingsUpdate)
Responses
Checks
GET
/v1/http-checks
Session or bearer token
List HTTP checks
Responses
POST
/v1/http-checks
Session or bearer token
Create an HTTP check
Request body: JSON (HTTPCheckRequest)
Responses
GET
/v1/http-checks/{id}
Session or bearer token
Get an HTTP check
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
PUT
/v1/http-checks/{id}
Session or bearer token
Update an HTTP check
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Request body: JSON (HTTPCheckRequest)
Responses
DELETE
/v1/http-checks/{id}
Session or bearer token
Delete an HTTP check
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
204 | Deleted | |
401 | Error | Error |
404 | Error | Error |
GET
/v1/smtp-checks
Session or bearer token
List SMTP checks
Responses
POST
/v1/smtp-checks
Session or bearer token
Create an SMTP check
Request body: JSON (SMTPCheckRequest)
Responses
GET
/v1/smtp-checks/{id}
Session or bearer token
Get an SMTP check
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
PUT
/v1/smtp-checks/{id}
Session or bearer token
Update an SMTP check
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Request body: JSON (SMTPCheckRequest)
Responses
DELETE
/v1/smtp-checks/{id}
Session or bearer token
Delete an SMTP check
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
204 | Deleted | |
401 | Error | Error |
404 | Error | Error |
PUT
/v1/tenants/{org}/checks
Session or bearer token
Declaratively reconcile all checks for an org
Replaces the full set of checks for the org with the request body, in one transaction. Items are created or updated by name. Any check that the body does not contain is deleted. The whole set is validated against the quota before anything is committed.
Parameters
| Name | In | Type | Description |
|---|
org required | path | string | |
Request body: JSON (object: http, smtp)
Responses
| Status | Description | Body |
|---|
200 | Reconciled | object: created, updated, deleted |
401 | Error | Error |
403 | Error | Error |
422 | Error | Error |
GET
/v1/checks
Session or bearer token
List all checks in the caller's org with their current status
Responses
GET
/v1/locations
Session or bearer token
List active probe locations a check can target
Responses
| Status | Description | Body |
|---|
200 | OK | object: locations |
401 | Error | Error |
GET
/v1/checks/{id}/status
Session or bearer token
Get a check's current alert status and per-location results
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
200 | OK | object: check_id, status, opened_at, locations |
404 | Error | Error |
GET
/v1/checks/metrics
Session or bearer token
Range-query one series for every check, averaged per check (dashboard sparklines)
Parameters
| Name | In | Type | Description |
|---|
metric | query | string | Metric to aggregate per check (zerodrop_* only). Defaults to zerodrop_request_latency_ms. |
range | query | string | Lookback window (Go duration, also d/w), e.g. 24h. Defaults to 24h. |
step | query | string | Sample step (Go duration, also d/w), e.g. 30m. Defaults to 30m. |
Responses
| Status | Description | Body |
|---|
200 | VictoriaMetrics range-query JSON | |
422 | Error | Error |
503 | Error | Error |
GET
/v1/checks/{id}/metrics
Session or bearer token
Range-query the metrics of a check (forced to the tenant of the caller)
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
metric | query | string | Defaults to zerodrop_probe_success. |
range | query | string | Lookback window as a Go duration, also accepting d (days) and w (weeks), e.g. 1h, 24h, 7d. Defaults to 1h. |
step | query | string | Sample step as a Go duration (d/w also accepted), e.g. 1m, 10m, 1h. Defaults to 1m. |
Responses
| Status | Description | Body |
|---|
200 | VictoriaMetrics range-query JSON | |
404 | Error | Error |
422 | Error | Error |
503 | Error | Error |
GET
/v1/checks/{id}/channels
Session or bearer token
List the channels notified for a check
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
200 | OK | object: channel_ids |
PUT
/v1/checks/{id}/channels
Session or bearer token
Replace the channels notified for a check
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Request body: JSON (object: channel_ids)
Responses
| Status | Description | Body |
|---|
204 | Updated | |
404 | Error | Error |
GET
/v1/checks/{id}/badge.svg
Public
Public status badge (shields.io-style SVG)
An SVG badge with the check name and the current status (up, down or unknown) in a matching color. Needs no authentication. Available only for a check with public_badge on. A check without it, or an unknown check, returns 404. Cached for 60 seconds.
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
200 | SVG badge | |
404 | Error | Error |
GET
/v1/checks/{id}/uptime.svg
Public
Public uptime badge (shields.io-style SVG)
An SVG badge with the check name and its 30-day success ratio, colored by threshold. Needs no authentication. Available only for a check with public_badge on. A check without it, or an unknown check, returns 404. Cached for 60 seconds.
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
200 | SVG badge | |
404 | Error | Error |
GET
/v1/checks/{id}/ssl.svg
Public
Public SSL-expiry badge (shields.io-style SVG)
An SVG badge with the check name and the number of days until its TLS certificate expires. The value is the soonest across all locations, colored by threshold. Needs no authentication. Available only for a check with public_badge on. A check without it, or an unknown check, returns 404. Cached for 60 seconds.
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
200 | SVG badge | |
404 | Error | Error |
GET
/v1/checks/{id}/incidents
Session or bearer token
List one check's incidents (newest first, paged)
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
limit | query | integer | Defaults to 50. |
offset | query | integer | Defaults to 0. |
Responses
Notifications
GET
/v1/notification-channels
Session or bearer token
List notification channels
Responses
| Status | Description | Body |
|---|
200 | OK | Channel array |
POST
/v1/notification-channels
Session or bearer token
Create a notification channel
Creates a destination for alerts. A webhook channel needs `config.url`, an email channel needs `config.address`. ZeroDrop refuses a destination it cannot use, with 422 and a message that says what to correct. A webhook URL must use https or http, must give a host, must not contain a user name or a password, and must be reachable from the public internet. An address such as `localhost` or `10.0.0.5` is refused. An email address must be a bare address, without a display name. The destination is stored with the leading and trailing spaces removed.
Request body: JSON (object: type, config)
Responses
GET
/v1/notification-channels/{id}
Session or bearer token
Get a notification channel
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
PUT
/v1/notification-channels/{id}
Session or bearer token
Update a notification channel's config
Replaces the config of the channel. The type is immutable, so delete and recreate the channel to change it. The destination is new and unconfirmed, so this call clears the verification. An email channel stops receiving alerts until it is verified again.
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Request body: JSON (object: config)
Responses
DELETE
/v1/notification-channels/{id}
Session or bearer token
Delete a notification channel
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
204 | Deleted | |
404 | Error | Error |
POST
/v1/notification-channels/{id}/verify
Session or bearer token
Start (or re-send) channel confirmation
An email channel uses double opt-in. ZeroDrop mails a confirmation link to the address, and the channel stays unverified until the recipient opens the link. A webhook channel is marked verified immediately. An email channel is also marked verified immediately when no mailer is configured.
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
204 | Verified | |
404 | Error | Error |
500 | Error | Error |
POST
/v1/notification-channels/{id}/test
Session or bearer token
Send a test notification to a channel
Sends one test notification to the channel now and reports what happened. Use it to make sure that a channel receives alerts before a real problem occurs. The test uses the same delivery path as a real alert, but it makes only one attempt and does not retry. The notification has the event type "test", so the receiver of a webhook can tell it from a real incident. An email channel must be verified first. ZeroDrop does not mail an address that did not confirm. The response is 200 when the request completed, also when the delivery failed. Read the status field for the result.
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
GET
/v1/notification-channels/{id}/checks
Session or bearer token
List the checks a channel is attached to
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
POST
/v1/notification-channels/verify/confirm
Public
Confirm an email channel using a confirmation token
Consumes the single-use token from the confirmation link and marks the channel verified. ZeroDrop mails that link to the address of the channel. This endpoint is public, because the recipient opens the link from their inbox.
Request body: JSON (object: token)
Responses
| Status | Description | Body |
|---|
204 | Channel confirmed | |
400 | Error | Error |
410 | Error | Error |
Maintenance
GET
/v1/maintenance-windows
Session or bearer token
List maintenance windows
Responses
POST
/v1/maintenance-windows
Session or bearer token
Create a maintenance window
Request body: JSON (MaintenanceWindowWrite)
Responses
GET
/v1/maintenance-windows/{id}
Session or bearer token
Get a maintenance window
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
PUT
/v1/maintenance-windows/{id}
Session or bearer token
Update a maintenance window
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Request body: JSON (MaintenanceWindowWrite)
Responses
DELETE
/v1/maintenance-windows/{id}
Session or bearer token
Delete a maintenance window
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
204 | Deleted | |
404 | Error | Error |
Incidents
GET
/v1/incidents
Session or bearer token
List incidents (newest first, paged)
Parameters
| Name | In | Type | Description |
|---|
limit | query | integer | Defaults to 50. |
offset | query | integer | Defaults to 0. |
Responses
| Status | Description | Body |
|---|
200 | OK | Incident array |
GET
/v1/incidents/{id}
Session or bearer token
Get an incident with its notification timeline
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
Status pages
GET
/v1/status-pages
Session or bearer token
List status pages
Responses
POST
/v1/status-pages
Session or bearer token
Create a public status page
Request body: JSON (StatusPageWrite)
Responses
GET
/v1/status-pages/{id}
Session or bearer token
Get a status page
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
PUT
/v1/status-pages/{id}
Session or bearer token
Update a status page
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Request body: JSON (StatusPageWrite)
Responses
DELETE
/v1/status-pages/{id}
Session or bearer token
Delete a status page
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
| Status | Description | Body |
|---|
204 | Deleted | |
404 | Error | Error |
Public
GET
/v1/public/status/{id}
Public
Public status page snapshot (unauthenticated, cached 30s)
The public status page for the given id. ZeroDrop pre-renders it and refreshes it periodically. Each listed check carries its current status, its 30-day uptime (maintenance excluded), and a full 30-day list of incidents and maintenance windows. The maintenance reason is public. Sends Cache-Control and ETag. An unknown id returns 404.
Parameters
| Name | In | Type | Description |
|---|
id required | path | string | |
Responses
GET
/v1/public/dashboard
Public
Public "Global Dashboard" snapshot (unauthenticated, heavily cached)
A view of the checks of the reserved public showcase tenant, grouped into categories. ZeroDrop pre-renders it and refreshes it periodically. The endpoint needs no authentication, and the server scopes it to the showcase org. Sends Cache-Control and ETag for edge caching and conditional caching. Returns 503 until the first snapshot exists, or when metrics are off.
Responses
| Status | Description | Body |
|---|
200 | The full dashboard payload. | object: generated_at, locations, categories |
304 | Not Modified | |
503 | Error | Error |
Other
GET
/v1/locations/health
Session or bearer token
Health of the shared probe fleet
Lists each fleet location, whether it reports fresh data, and whether it is quarantined. Also returns a count of the reporting locations and the total locations. This is cross-tenant infrastructure status, and it is identical for every user.
Responses
| Status | Description | Body |
|---|
200 | OK | object: reporting, total, locations |
401 | Error | Error |
GET
/v1/audit-events
Session or bearer token
List the org's audit log (newest first, paged)
Parameters
| Name | In | Type | Description |
|---|
limit | query | integer | Defaults to 50. |
offset | query | integer | Defaults to 0. |
Responses
Schemas
Error
| Field | Type | Description |
|---|
error required | string | Human-readable |
Credentials
| Field | Type | Description |
|---|
email required | string (email) | |
password required | string | |
turnstile_token | string | Cloudflare Turnstile token. Required when Turnstile is enabled (see GET /v1/auth/config). |
AuthConfig
| Field | Type | Description |
|---|
turnstile_site_key required | string | Cloudflare Turnstile site key for the SPA to render the widget. Empty when Turnstile is off. |
Settings
| Field | Type | Description |
|---|
org_name required | string | Account/organization display name |
timezone required | string | IANA timezone name for displaying times, e.g. Europe/Copenhagen |
max_checks required read-only | integer | Maximum number of checks the org may create |
min_interval_seconds required read-only | integer | Minimum allowed check interval in seconds |
notify_repeat_interval_seconds required | integer | Re-notify cadence for ongoing incidents, in seconds; 0 disables reminders |
SettingsUpdate
All fields are optional. The API updates only the fields that are present.
| Field | Type | Description |
|---|
org_name | string | Account/organization display name (1–80 chars) |
timezone | string | IANA timezone name for displaying times, e.g. Europe/Copenhagen |
notify_repeat_interval_seconds | integer | Re-notify cadence for ongoing incidents, in seconds; 0 (off) or 300–604800 |
TOTPRequired
| Field | Type | Description |
|---|
totp_required required | boolean | True when a TOTP code is needed to finish sign-in |
TOTPCode
| Field | Type | Description |
|---|
code required | string | Six-digit code from the authenticator app |
Passkey
| Field | Type | Description |
|---|
id required | string | |
name required | string | |
created_at required | string (date-time) | |
ApiToken
| Field | Type | Description |
|---|
id required | string | |
name required | string | |
hint | string | Non-sensitive fingerprint of the token (prefix + a few chars, e.g. zd_a1b2…9z0f). Empty for tokens created before this was captured. |
created_at required | string (date-time) | |
last_used_at | string (date-time) | |
expires_at | string (date-time) | |
ApiTokenSecret
All fields of ApiToken, plus:
| Field | Type | Description |
|---|
token required | string | The raw secret, shown only once at creation |
Channel
| Field | Type | Description |
|---|
id | string | |
type | string (webhook | email) | |
config | object | |
verified | boolean | |
created_at | string (date-time) | |
check_count | integer | How many checks notify through this channel |
ChannelCheckRef
| Field | Type | Description |
|---|
id | string | |
name | string | |
type | string (http | smtp) | |
ChannelTestResult
| Field | Type | Description |
|---|
status required | string (sent | failed | skipped) | "sent" when the channel accepted the notification. "failed" when the delivery did not complete. "skipped" when ZeroDrop did not try, for example because the email address is not verified. |
response required | string | What the channel answered. For a webhook this is the HTTP status code, or the reason the request did not complete. For email it names the transport. When the status is "skipped" it gives the reason. |
duration_ms required | integer (int64) | How long the delivery attempt took, in milliseconds. |
AuditEvent
| Field | Type | Description |
|---|
id required | string | |
user_id | string | The acting user (empty for unattributed events) |
user_email | string | The acting user's email (empty for unattributed events or a since-deleted user) |
event_type required | string | Dot-namespaced event id, e.g. auth.login.success |
ip | string | |
geo_country | string | ISO country code |
geo_city | string | |
user_agent | string | |
method | string | HTTP method of the API request |
path | string | API endpoint |
ui_path | string | Console route the action came from |
detail | object | Event-specific extra fields |
created_at required | string (date-time) | |
MaintenanceWindow
| Field | Type | Description |
|---|
id | string | |
check_id | string | |
starts_at | string (date-time) | |
ends_at | string (date-time) | |
reason | string | |
MaintenanceWindowWrite
| Field | Type | Description |
|---|
check_id | string | Null suppresses all of the org's checks |
starts_at required | string (date-time) | |
ends_at required | string (date-time) | |
reason | string | |
StatusPage
| Field | Type | Description |
|---|
id | string | ULID; also the public page identifier in the URL |
title | string | |
description | string | |
url read-only | string | The public URL of the page, for example https://zerodrop.app/status/{id}. |
created_at | string (date-time) | |
check_ids | string[] | Checks shown on the page, in display order |
StatusPageWrite
| Field | Type | Description |
|---|
title required | string | |
description | string | |
check_ids | string[] | Checks to show, in display order |
PublicStatusPage
The unauthenticated status page payload. The maintenance reason is public.
| Field | Type | Description |
|---|
id | string | |
title | string | |
description | string | |
generated_at | string (date-time) | |
window_days | integer | |
checks | object[] | |
Incident
| Field | Type | Description |
|---|
id | string | |
check_id | string | |
check_name | string | |
opened_at | string (date-time) | |
resolved_at | string (date-time) | |
cause | string | |
failing_locations | string[] | |
IncidentNotification
One notification delivery recorded for an incident.
| Field | Type | Description |
|---|
id | string | |
event | string | The transition that triggered it, e.g. fired or resolved |
channel_type | string (webhook | email) | |
target | string | The channel's destination (email address or webhook URL) |
sent_at | string (date-time) | |
status | string | sent or failed |
response | string | Delivery detail: an HTTP status code or an error message |
IncidentDetail
All fields of Incident, plus:
| Field | Type | Description |
|---|
notifications | IncidentNotification[] | |
HTTPCheckRequest
| Field | Type | Description |
|---|
name required | string | Unique per org |
enabled | boolean | |
interval_seconds | integer | Defaults to 60s (1 minute), the minimum |
timeout_ms | integer | |
consensus_fraction | number | Fraction of live locations that must fail (0, 1] |
consensus_floor | integer | Minimum number of locations that must report down simultaneously to alert |
fire_evals | integer | Consecutive breaching evals before firing |
resolve_evals | integer | Consecutive healthy evals before resolving |
url required | string | |
method | string | |
expected_status | integer | |
body_pattern | string | Substring/regex expected in the body |
follow_redirects | boolean | |
max_redirects | integer | |
verify_cert | boolean | Whether the server's TLS certificate must validate against the trust store |
min_cert_days | integer | Fail the check when the TLS certificate has fewer than this many days of validity left; 0 disables the check |
public_badge | boolean | Expose public status/uptime/SSL badges for this check at /v1/checks/{id}/badge.svg, /uptime.svg and /ssl.svg (unauthenticated SVG) |
locations read-only | string[] | Assigned by the server. Every check probes from all active locations |
HTTPCheck
All fields of HTTPCheckRequest, plus:
| Field | Type | Description |
|---|
id required | string | |
type required | string (http) | |
created_at required | string (date-time) | |
updated_at required | string (date-time) | |
SMTPCheckRequest
| Field | Type | Description |
|---|
name required | string | Unique per org |
enabled | boolean | |
interval_seconds | integer | Defaults to 60s (1 minute), the minimum |
timeout_ms | integer | |
consensus_fraction | number | Fraction of live locations that must fail (0, 1] |
consensus_floor | integer | Minimum number of locations that must report down simultaneously to alert |
fire_evals | integer | Consecutive breaching evals before firing |
resolve_evals | integer | Consecutive healthy evals before resolving |
host required | string | |
port | integer | |
starttls | boolean | |
expected_welcome_pattern | string | Substring/regex expected in the 220 banner |
verify_cert | boolean | Whether the STARTTLS certificate must validate against the trust store |
min_cert_days | integer | Fail the check when the STARTTLS certificate has fewer than this many days of validity left; 0 disables the check |
public_badge | boolean | Expose public status/uptime/SSL badges for this check at /v1/checks/{id}/badge.svg, /uptime.svg and /ssl.svg (unauthenticated SVG) |
locations read-only | string[] | Assigned by the server. Every check probes from all active locations |
SMTPCheck
All fields of SMTPCheckRequest, plus:
| Field | Type | Description |
|---|
id required | string | |
type required | string (smtp) | |
created_at required | string (date-time) | |
updated_at required | string (date-time) | |
CheckSummary
| Field | Type | Description |
|---|
id required | string | |
name required | string | |
type required | string (http | smtp) | |
status required | string (ok | firing | unknown) | Current alert status |
opened_at | string (date-time) | When the current incident opened |
target required | string | HTTP url, or smtp host:port |
enabled required | boolean | |
interval_seconds required | integer | |
public_badge | boolean | Whether the check exposes public status/uptime/SSL badges |
locations required | string[] | |
reporting_locations required | integer | How many of the locations reported in the last 5 minutes |
CheckList
| Field | Type | Description |
|---|
checks required | CheckSummary[] | |