API reference

This page lists every endpoint of the Monitorable REST API v1, generated from the live OpenAPI document at https://api.monitorable.io/openapi.json (version 2026-11-03). Authentication and scopes are on API keys and scopes; every error body is described on Errors.

Account

The calling API key, its organization, members, plan, limits and usage.

GET /v1/me

GetMe

The calling key: name, scopes, role, organization and plan. Any key.

Responses

Status	Description
200	Success — Me
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
expires_at	string (RFC 3339)	When the key stops working; null for a key that never expires.
key_id	integer (int32)	The key’s id, as listed in the dashboard.
key_name	string	The name given to the key at creation.
organization_id	integer (int32)	The organization the key belongs to.
organization_name	string	The organization’s name.
plan_name	string	The organization’s plan, e.g. “Pro”. Empty when billing is not enabled.
role	string	“admin” or “member”: the most the key can do, narrowed by its scopes.
scopes	string[]	The key’s scopes, e.g. “servers:read”.

GET /v1/organization

GetOrganization

The key’s organization with its plan limits and current usage. Requires account:read.

Responses

Status	Description
200	Success — Organization
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
created_at	string (RFC 3339)
id	integer (int32)
limits	object	Count limits of the owner’s plan keyed by limit name (e.g. “max_servers”, “max_api_keys”). Account-wide: shared by every organization of the owner. Empty when billing is not enabled.
name	string
plan_name	string	The plan’s display name, e.g. “Pro”. Empty when billing is not enabled.
usage	Usage	Current usage.

GET /v1/organization/members

ListMembers

Members of the key’s organization. Requires account:read.

Responses

Status	Description
200	Success — ListMembersResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
data	Member[]

Agent

The commands that update and remove the Monitorable agent on a host.

GET /v1/agent/commands

GetCommands

The shell commands that update and uninstall the agent on a host. They carry no key and no tenant data, so any key may read them.

Responses

Status	Description
200	Success — AgentCommands
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
uninstall_command	string	Removes the agent and its service from the host.
update_command	string	Re-runs the installer to move the agent to the latest version.

Alerts

Alert muting, templates and channels of the key’s organization.

GET /v1/alert-templates

ListTemplates

Lists the organization’s alert templates with their rules, creating the default template on first use. Requires alerts:read.

Responses

Status	Description
200	Success — ListTemplatesResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
data	AlertTemplate[]	The templates. The default template is created on first use, so the list is never empty.

GET /v1/notification-channels

ListChannels

Lists the organization’s notification channels with the outcome of their latest delivery. A channel’s settings (URLs, tokens, addresses) are never returned. Requires alerts:read.

Responses

Status	Description
200	Success — ListChannelsResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
data	NotificationChannel[]	The channels.

PUT /v1/servers/{id}/alert-template

SetServerAlertTemplate

Assigns an alert template to a server. A template_id of 0 resets the server to the organization’s default template. An unknown template (or one of another organization) answers 404. Requires alerts:write and an admin-role key.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Request body (JSON)

Field	Type	Description
template_id	integer (int32)	The template’s id. 0 means the organization’s default template.

Responses

Status	Description
200	Success — SetServerAlertTemplateResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
server_id	integer (int32)	The server’s id.
template_id	integer (int32)	The id that was requested: 0 means the server follows the organization’s default template.

POST /v1/servers/{id}/alerts:mute

MuteServerAlerts

Mutes a server’s alerts: incidents still open and still record, but no notification is sent while the mute lasts. Without until the mute lasts until it is lifted; with until it ends then (in the future, at most 366 days ahead). Muting an already muted server replaces the end and the reason. Answers the resulting mute state. Requires alerts:write and an admin-role key.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Request body (JSON)

Field	Type	Description
reason	string	Why the server is muted, shown in the dashboard. At most 200 characters, no control characters. Optional.
until	string (RFC 3339)	When the mute ends, RFC 3339 (for example 2026-11-04T06:00:00Z). Omit to mute until lifted. Must be in the future and at most 366 days ahead.

Responses

Status	Description
200	Success — MuteState
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
muted	boolean	True while the server’s alerts are muted.
reason	string	The reason given for the mute. Empty when none was given or the server is not muted.
server_id	integer (int32)	The server’s id.
until	string (RFC 3339)	When a timed mute ends. null when the mute has no end or the server is not muted.

POST /v1/servers/{id}/alerts:unmute

UnmuteServerAlerts

Lifts a server’s mute now. Unmuting a server that is not muted answers 200 with muted false. Requires alerts:write and an admin-role key.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Responses

Status	Description
200	Success — MuteState
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
muted	boolean	True while the server’s alerts are muted.
reason	string	The reason given for the mute. Empty when none was given or the server is not muted.
server_id	integer (int32)	The server’s id.
until	string (RFC 3339)	When a timed mute ends. null when the mute has no end or the server is not muted.

Enroll

EnrollService registers the host that calls it.

POST /v1/enroll

Enroll

Enroll creates a server for this host, or — when server_ref names a server this organization already has — rotates that server’s agent key and keeps the row. Answers 201 when it created a server and 200 when it rotated the key of an existing one. Requires the servers:enroll scope and an admin-role key. Idempotency-Key is ignored: server_ref is the retry handle.

Request body (JSON)

Field	Type	Description
name	string	The server’s display name: 1–100 characters after trimming. The installer sends the hostname by default. Ignored when server_ref matches an existing server (enroll never renames).
server_ref	string	Optional: the host’s stable id (instance id, Terraform self.id, inventory_hostname, VMID), at most 128 characters, no whitespace or control characters. A second enroll with the same server_ref rotates the existing server’s agent key instead of creating another server.

Responses

Status	Description
200	Re-enrolled: server_ref matched an existing server, whose agent key was rotated; agent_api_key is shown once. — EnrollResponse
201	Created: a new server; agent_api_key is shown once. — EnrollResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
402	plan_limit_reached: the plan’s limit for this resource is reached.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
agent_api_key	string	The agent key, shown once.
ingest_endpoint	string	The OTLP endpoint the agent writes to (its MONITORABLE_ENDPOINT).
name	string	The server’s name: the existing one on a rotation (enroll never renames).
rotated	boolean	True when server_ref matched an existing server and its key was rotated.
server_id	integer (int32)	The server’s id.

Response fields (201)

Field	Type	Description
agent_api_key	string	The agent key, shown once.
ingest_endpoint	string	The OTLP endpoint the agent writes to (its MONITORABLE_ENDPOINT).
name	string	The server’s name: the existing one on a rotation (enroll never renames).
rotated	boolean	True when server_ref matched an existing server and its key was rotated.
server_id	integer (int32)	The server’s id.

Incidents

Alert incidents of the key’s organization.

GET /v1/incidents

List

Lists incidents, newest first (by start time, then id). Only open incidents (pending or firing) are listed unless state says otherwise. Page with limit and cursor. Requires alerts:read.

Parameters

Name	In	Type	Description
state	query	string	open (pending or firing, the default), resolved, or all.
server_id	query	integer (int32)	Only incidents of this server. 0 or omitted means every server.
since	query	string (RFC 3339)	Only incidents that started at or after this time, RFC 3339 (for example 2026-10-01T00:00:00Z).
limit	query	integer (int32)	Page size: default 25, at most 100 (larger values are treated as 100).
cursor	query	string	The next_cursor of the previous page.

Responses

Status	Description
200	Success — ListIncidentsResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
data	Incident[]	The incidents of this page, newest first.
next_cursor	string	Pass as cursor to fetch the next page. Empty string when this is the last page.

GET /v1/incidents/{id}

Get

One incident with the notifications sent for it, oldest first (at most 200). Requires alerts:read.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The incident’s id.

Responses

Status	Description
200	Success — IncidentDetail
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
deliveries	Delivery[]	The notification attempts, oldest first (at most 200). Empty when none were sent.
incident	Incident	The incident.

POST /v1/incidents/{id}:acknowledge

Acknowledge

Acknowledges an open incident on behalf of the API key, which the dashboard shows as “(API key)”. Acknowledging an incident that is already acknowledged answers 200 with the incident unchanged. A resolved incident answers 409 incident_resolved. Requires alerts:write and an admin-role key.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The incident’s id.

Responses

Status	Description
200	Success — Incident
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
409	incident_resolved: the incident is already resolved.
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
acked_at	string (RFC 3339)	When it was acknowledged. null until it is.
acked_by	string	Who acknowledged it: the API key’s name when acked_by_api_key is true, else the user’s name. A user with no display name shows as their email, to admin-role keys only (member emails are admin-only); for any other key it is empty. Empty when not acknowledged.
acked_by_api_key	boolean	True when an API key acknowledged the incident, not a user.
description	string	A one-sentence description of the incident.
entity	string	What the rule concerns when it is not the whole server (a mount point or network interface). Empty for server-wide rules.
escalated_at	string (RFC 3339)	When the unacknowledged-escalation notification went out. null until it has.
fired_at	string (RFC 3339)	When the incident started firing. null while pending.
id	integer (int32)	The incident’s id.
last_notified_at	string (RFC 3339)	When a notification for this incident was last sent. null until one has.
reminders_sent	integer (int32)	How many reminders were sent while it stayed unacknowledged.
resolve_reason	string	Why it resolved. Empty until it does.
resolved_at	string (RFC 3339)	When the incident resolved. null until it does.
rule_type	string	The rule that produced it, e.g. cpu_usage, memory_usage, disk_usage, agent_offline.
server_id	integer (int32)	The server the incident concerns.
server_muted	boolean	True while the server’s alerts are muted.
server_name	string	The server’s display name.
started_at	string (RFC 3339)	When the breach began.
state	string	pending (breaching, not yet confirmed), firing, or resolved.
threshold	number | null	The threshold the rule compares against, in the rule’s unit. Omitted when the rule has none.
value	number | null	The measured value at the last evaluation, in the rule’s unit. Omitted when the rule has no value (agent_offline).
window_minutes	integer | null	How many minutes the breach must hold. Omitted when the rule has no window.

POST /v1/incidents/{id}:unacknowledge

Unacknowledge

Withdraws an acknowledgement, whoever made it, so reminders resume. Un-acknowledging an incident that is not acknowledged answers 200 with the incident unchanged. A resolved incident answers 409 incident_resolved. Requires alerts:write and an admin-role key.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The incident’s id.

Responses

Status	Description
200	Success — Incident
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
409	incident_resolved: the incident is already resolved.
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
acked_at	string (RFC 3339)	When it was acknowledged. null until it is.
acked_by	string	Who acknowledged it: the API key’s name when acked_by_api_key is true, else the user’s name. A user with no display name shows as their email, to admin-role keys only (member emails are admin-only); for any other key it is empty. Empty when not acknowledged.
acked_by_api_key	boolean	True when an API key acknowledged the incident, not a user.
description	string	A one-sentence description of the incident.
entity	string	What the rule concerns when it is not the whole server (a mount point or network interface). Empty for server-wide rules.
escalated_at	string (RFC 3339)	When the unacknowledged-escalation notification went out. null until it has.
fired_at	string (RFC 3339)	When the incident started firing. null while pending.
id	integer (int32)	The incident’s id.
last_notified_at	string (RFC 3339)	When a notification for this incident was last sent. null until one has.
reminders_sent	integer (int32)	How many reminders were sent while it stayed unacknowledged.
resolve_reason	string	Why it resolved. Empty until it does.
resolved_at	string (RFC 3339)	When the incident resolved. null until it does.
rule_type	string	The rule that produced it, e.g. cpu_usage, memory_usage, disk_usage, agent_offline.
server_id	integer (int32)	The server the incident concerns.
server_muted	boolean	True while the server’s alerts are muted.
server_name	string	The server’s display name.
started_at	string (RFC 3339)	When the breach began.
state	string	pending (breaching, not yet confirmed), firing, or resolved.
threshold	number | null	The threshold the rule compares against, in the rule’s unit. Omitted when the rule has none.
value	number | null	The measured value at the last evaluation, in the rule’s unit. Omitted when the rule has no value (agent_offline).
window_minutes	integer | null	How many minutes the breach must hold. Omitted when the rule has no window.

Metrics

Metric reads for one server of the key’s organization. Requires metrics:read.

GET /v1/servers/{id}/metrics

GetRange

A time range of metrics as named series. start defaults to 24 hours before end and end to now; start must be before end. A start older than the plan’s retention window is refused with 403 range_not_in_plan rather than silently shortened. A start before the server’s first data point is moved up to it. step_seconds defaults to 300, is at least 60, and is raised so no series exceeds 1000 points (about span / 1000 seconds, rounded up to a whole minute); the step used is returned. Ranges longer than 7 days also count against a stricter rate limit.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.
start	query	string (RFC 3339)	Start of the range, RFC 3339 (for example 2026-10-01T00:00:00Z). Defaults to 24 hours before end. Must be on or after 2000-01-01.
end	query	string (RFC 3339)	End of the range, RFC 3339. Defaults to now; an end more than 5 minutes in the future is treated as now.
step_seconds	query	integer (int32)	Spacing of the points in seconds: default 300, minimum 60. Raised to keep every series at or under 1000 points.
series	query	string[]	Which groups to return: cpu, memory, swap, disk, network, connections, ports. Repeat the parameter (?series=cpu&series=memory) or separate values with commas (?series=cpu,memory). Empty returns every group.

Responses

Status	Description
200	Success — MetricsRange
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
end	string (RFC 3339)	The end of the range returned.
series	Series[]	The series, grouped in the order cpu, memory, swap, disk, network, connections, ports; within a group in the order listed in the API documentation, and per-device series sorted by device. Empty when the requested window holds no data.
server_id	integer (int32)	The server’s id.
start	string (RFC 3339)	The start of the range returned: the requested start, or the server’s first data point when that is later.
step_seconds	integer (int32)	The step used, in seconds. This can be larger than the step requested.

GET /v1/servers/{id}/metrics/current

GetCurrent

The latest value of each headline metric.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Responses

Status	Description
200	Success — CurrentMetrics
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
cpu	CurrentCpu	Processor load and usage.
disk	CurrentDisk	The root filesystem.
memory	CurrentMemory	Memory in bytes.
network	CurrentNetwork	Network throughput.
server_id	integer (int32)	The server’s id.
swap	CurrentSwap	Swap space.
timestamp	string (RFC 3339)	When the snapshot was taken. null if it has no time.

Servers

Servers monitored by the key’s organization.

GET /v1/servers

List

Lists the organization’s servers, oldest id first, with their liveness and triage state. Requires servers:read.

Parameters

Name	In	Type	Description
status	query	string	Return only servers with this liveness: online, stale, offline or dormant; any other value is a 400. Empty returns every server.
q	query	string	Return only servers whose name contains this text, ignoring case.
limit	query	integer (int32)	Page size: 1-100, default 25; values above 100 are clamped to 100.
cursor	query	string	The next_cursor of the previous page. Empty for the first page.

Responses

Status	Description
200	Success — ListServersResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
data	Server[]	The servers of this page, ordered by id ascending.
next_cursor	string	Pass as cursor to fetch the next page. Empty string when this is the last page.

POST /v1/servers

Create

Registers a new server and returns its agent key, shown once, with the install command. Answers 201. Requires servers:write and an admin-role key. Send an Idempotency-Key header (at most 64 characters) to make retries safe: a retry with the same key and name answers 200 with the same server, without the key (see recovery), and creates nothing. While the first request is still running, a retry with the same key answers 503 idempotency_unavailable: wait a moment and retry.

Parameters

Name	In	Type	Description
Idempotency-Key	header	string	A client-chosen key of at most 64 characters. Replays with the same key and body within 24 h answer 200 with the same server and no key material.

Request body (JSON)

Field	Type	Description
name	string	The server’s display name, 1 to 100 characters.

Responses

Status	Description
200	Idempotency-Key replay: same server; agent_api_key and install_command omitted; recovery set — CreateServerResponse
201	Created. agent_api_key and install_command are shown once. — CreateServerResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
402	plan_limit_reached: the plan’s limit for this resource is reached.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
422	idempotency_key_reused: the Idempotency-Key was already used with a different request body.
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.
503	idempotency_unavailable: the idempotency store is unavailable or a request with the same key is still in progress. Retry-After says when to retry an in-progress request.

Response fields (200)

Field	Type	Description
agent_api_key	string | null	The agent’s API key. Shown once, never retrievable again. Omitted on an Idempotency-Key replay (see recovery).
install_command	string | null	A shell command that installs the agent with the key. Omitted on an Idempotency-Key replay.
recovery	string | null	Present only on a replay of the same Idempotency-Key, which answers 200: how to get a fresh key, “POST /v1/servers//agent-key:rotate”. Omitted on the first response.
server	Server	The new server.

Response fields (201)

Field	Type	Description
agent_api_key	string | null	The agent’s API key. Shown once, never retrievable again. Omitted on an Idempotency-Key replay (see recovery).
install_command	string | null	A shell command that installs the agent with the key. Omitted on an Idempotency-Key replay.
recovery	string | null	Present only on a replay of the same Idempotency-Key, which answers 200: how to get a fresh key, “POST /v1/servers//agent-key:rotate”. Omitted on the first response.
server	Server	The new server.

GET /v1/servers/{id}

Get

One server: the same row List returns. Requires servers:read.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Responses

Status	Description
200	Success — Server
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
agent_version	string	The agent version the server reports, e.g. “1.6.0”. Empty if unknown.
alert_template_id	integer (int32)	The alert template assigned to the server; 0 means the organization’s default template.
alerts_muted	boolean	True while alerts for this server are muted (indefinitely or until a set time that has not passed).
alerts_muted_reason	string	The reason given for the mute. Empty when not muted.
alerts_muted_until	string (RFC 3339)	When a timed mute ends. null for an indefinite mute or when not muted.
country_code	string	Lowercase ISO 3166-1 alpha-2 country code of the address. Empty when unknown.
created_at	string (RFC 3339)	When the server was registered.
created_via	string	How the server was registered: dashboard, api or enroll.
id	integer (int32)	The server’s id.
ip	string	The address Monitorable sees the agent connect from: the IPv4 when known, else the IPv6. Empty until the agent first reports.
ipv4	string	The IPv4 address Monitorable sees the agent connect from.
ipv6	string	The IPv6 address Monitorable sees the agent connect from.
last_seen_at	string (RFC 3339)	When the agent last reported. null if it never has.
location	string	Country of the address, e.g. “Germany”. Empty when unknown.
name	string	The server’s display name.
open_incidents	integer (int32)	Incidents on this server that are not resolved, pending and acknowledged ones included. 0 while a mute holds them back.
status	string	Liveness from the last data received: online, stale, offline or dormant.
triage	string	Triage tier: needs_attention (an unacknowledged firing incident), acknowledged, unreachable (not online, no incident), healthy or dormant.
unacked_firing	integer (int32)	Firing incidents on this server nobody has acknowledged. 0 while a mute holds them back.
uptime_seconds	number (double)	Seconds since the server booted, as last reported.

DELETE /v1/servers/{id}

Delete

Deletes a server and its data. Answers 204 with no body. Requires servers:write and an admin-role key.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Responses

Status	Description
204	Deleted; no body.
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

PATCH /v1/servers/{id}

Update

Renames a server. Requires servers:write and an admin-role key.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Request body (JSON)

Field	Type	Description
name	string	The new display name.

Responses

Status	Description
200	Success — Server
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
agent_version	string	The agent version the server reports, e.g. “1.6.0”. Empty if unknown.
alert_template_id	integer (int32)	The alert template assigned to the server; 0 means the organization’s default template.
alerts_muted	boolean	True while alerts for this server are muted (indefinitely or until a set time that has not passed).
alerts_muted_reason	string	The reason given for the mute. Empty when not muted.
alerts_muted_until	string (RFC 3339)	When a timed mute ends. null for an indefinite mute or when not muted.
country_code	string	Lowercase ISO 3166-1 alpha-2 country code of the address. Empty when unknown.
created_at	string (RFC 3339)	When the server was registered.
created_via	string	How the server was registered: dashboard, api or enroll.
id	integer (int32)	The server’s id.
ip	string	The address Monitorable sees the agent connect from: the IPv4 when known, else the IPv6. Empty until the agent first reports.
ipv4	string	The IPv4 address Monitorable sees the agent connect from.
ipv6	string	The IPv6 address Monitorable sees the agent connect from.
last_seen_at	string (RFC 3339)	When the agent last reported. null if it never has.
location	string	Country of the address, e.g. “Germany”. Empty when unknown.
name	string	The server’s display name.
open_incidents	integer (int32)	Incidents on this server that are not resolved, pending and acknowledged ones included. 0 while a mute holds them back.
status	string	Liveness from the last data received: online, stale, offline or dormant.
triage	string	Triage tier: needs_attention (an unacknowledged firing incident), acknowledged, unreachable (not online, no incident), healthy or dormant.
unacked_firing	integer (int32)	Firing incidents on this server nobody has acknowledged. 0 while a mute holds them back.
uptime_seconds	number (double)	Seconds since the server booted, as last reported.

POST /v1/servers/{id}/agent-key:rotate

RotateAgentKey

Replaces the server’s agent key and returns the new one, shown once, with the install command. The old key stops working. Requires servers:write and an admin-role key.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Responses

Status	Description
200	Success — RotateAgentKeyResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
agent_api_key	string	The new agent API key. Shown once, never retrievable again.
install_command	string	A shell command that installs the agent with the new key.

GET /v1/servers/{id}/containers

ListContainers

The Docker containers the agent reported. Requires servers:read.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Responses

Status	Description
200	Success — ListServerContainersResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
data	Container[]	One entry per container.

GET /v1/servers/{id}/disks

ListDisks

The physical disks and their SMART health. Requires servers:read.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Responses

Status	Description
200	Success — ListServerDisksResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
data	Disk[]	One entry per disk.

GET /v1/servers/{id}/metadata

GetMetadata

Hardware and operating-system facts the agent reported. Requires servers:read.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Responses

Status	Description
200	Success — ServerMetadata
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
agent_version	string	The agent version the server reports. Empty if unknown.
architecture	string	CPU architecture, e.g. “amd64”.
cloud_provider	string	Cloud provider, e.g. “aws”. Empty off cloud or when unknown.
cpu_cores	integer (int32)	Physical CPU cores.
cpu_frequency_current_mhz	number (double)	Current CPU frequency in MHz.
cpu_model	string	CPU model name.
cpu_temperature	number (double)	CPU temperature in degrees Celsius; 0 when the server has no readable sensor.
cpu_threads	integer (int32)	Logical CPU threads.
hostname	string	The host name.
instance_id	string	The cloud provider’s instance id. Empty when unknown.
kernel_version	string	Kernel version.
last_boot_time	string (RFC 3339)	When the server last booted. null when unknown.
os_name	string	Operating system name, e.g. “Ubuntu”.
os_version	string	Operating system version, e.g. “24.04”.
permission_errors	string[]	Codes of the readings the agent could not take for lack of permissions, e.g. “temperature_monitoring_requires_root”.
reboot_required	boolean	True when the operating system asks for a reboot (pending updates).
region	string	The cloud region. Empty when unknown.
server_id	integer (int32)	The server’s id.
total_ram_bytes	number (double)	Installed RAM in bytes.
updated_at	string (RFC 3339)	When this metadata was last refreshed.
uptime_seconds	number (double)	Seconds since the server booted.

GET /v1/servers/{id}/ports

ListPorts

The ports the server listens on, and the snapshot they came from. Requires servers:read.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Responses

Status	Description
200	Success — ListServerPortsResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
data	ListeningPort[]	One entry per port.
snapshot	PortSnapshot	The snapshot the ports came from. Always present; received_at is null when the server has no port snapshot (an agent that predates port reporting, or the feature is off).

GET /v1/servers/{id}/services

ListServices

The systemd services the agent reported. Requires servers:read.

Parameters

Name	In	Type	Description
id	path	integer (int32)	The server’s id.

Responses

Status	Description
200	Success — ListServerServicesResponse
400	invalid_argument: a parameter or body field is malformed or out of range.
401	The key is missing, invalid, expired or revoked, or the account is suspended.
403	The key lacks what the call needs: insufficient_scope, insufficient_role, api_access_not_in_plan or range_not_in_plan.
404	not_found: no such resource in the key’s organization (a resource of another organization is indistinguishable).
429	rate_limited. The RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers say when to retry.

Response fields (200)

Field	Type	Description
data	Service[]	One entry per service.