Schemas

Download schema

Advisory

id

string · required

OSV ID of the advisory.

Example: DSA-5532-1

family

string · required

Distribution family: debian, ubuntu, almalinux, rocky or rhel. New values may be added.

Example: debian

kind

AdvisoryKind · required

cve for a distribution's record of one CVE across its releases (DEBIAN-CVE, UBUNTU-CVE), notice for a security notice that ships fixed packages (DSA, DLA, USN, ALSA, RLSA, RHSA).


`cve` A distribution's record of one CVE across its releases, including unfixed ones: DEBIAN-CVE-… or UBUNTU-CVE-….
`notice` A security notice that ships fixed packages, usually for several CVEs: DSA, DLA, USN, ALSA, RLSA or RHSA.
`advisory` A package ecosystem's advisory of a vulnerable package: a GitHub (GHSA), Drupal or Packagist (PKSA) security advisory.
`malware` A package published with malicious code, every listed version is affected: MAL-….

summary

string | null · required

Short title, null for CVE records.

Example: openssl - security update

details

string | null · required

Description, cut to a few hundred characters.

severity

AdvisorySeverity · required

Severity normalised across distributions: the distribution's rating when it has one, otherwise the CVSS v3 band. Debian and Ubuntu notices take the highest rating of the CVEs they fix.


`critical` Ubuntu critical, Red Hat Critical, or a CVSS base score of 9.0 or higher.
`high` Ubuntu high, Red Hat Important, Debian high, or a CVSS base score from 7.0.
`medium` Ubuntu medium, Red Hat Moderate, Debian medium, or a CVSS base score from 4.0.
`low` Ubuntu low, Red Hat Low, Debian low, or a CVSS base score below 4.0.
`negligible` Ubuntu negligible or Debian unimportant: no practical impact on the distribution's builds.
`unknown` Not rated yet.

cvss

object | null · required

The highest CVSS v3 base score and its vector, null without a CVSS v3 vector.

array · required

CVE IDs the advisory covers.

Example: ["CVE-2023-5363"]

aliases

string[] · required

CVE IDs and related advisories of the same distribution, such as the DEBIAN-CVE records a DSA fixes, or the RHSA an AlmaLinux erratum rebuilds.

Example: ["CVE-2023-5363","DEBIAN-CVE-2023-5363"]

array · required

A few references, advisories and fixes first.

url

string · required

The distribution's page of the advisory, or its OSV.dev page.

Example: https://security-tracker.debian.org/tracker/DSA-5532

published_at

string | null · required

ISO 8601 publication timestamp, null when unknown.

modified_at

string · required

ISO 8601 timestamp of the last change to the advisory.

AdvisoryPackage[] · required

Affected packages per imported release with their version range.

AdvisoryKind

string


`cve` A distribution's record of one CVE across its releases, including unfixed ones: DEBIAN-CVE-… or UBUNTU-CVE-….
`notice` A security notice that ships fixed packages, usually for several CVEs: DSA, DLA, USN, ALSA, RLSA or RHSA.
`advisory` A package ecosystem's advisory of a vulnerable package: a GitHub (GHSA), Drupal or Packagist (PKSA) security advisory.
`malware` A package published with malicious code, every listed version is affected: MAL-….

AdvisoryPackage

release

string · required

Release such as debian:12, ubuntu:22.04, ubuntu-pro:16.04 (Ubuntu Pro fixes), almalinux:9, rocky:9 or rhel:9.

Example: debian:12

name

string · required

Package name as the distribution publishes it: the source package for Debian, Ubuntu and Rocky Linux, the binary package for AlmaLinux and Red Hat.

Example: openssl

introduced

string | null · required

First affected version, null when every earlier version is affected.

fixed

string | null · required

First fixed version, null when no fix is released for the release.

Example: 3.0.11-1~deb12u2

last_affected

string | null · required

Last affected version for a range without a fix, usually null.

AdvisorySeverity

string

Advisory severity normalised across distributions and package ecosystems: the distribution's own rating when it has one (Ubuntu priority, the Red Hat rating of AlmaLinux and Rocky errata, Debian's unimportant) or GitHub's rating of a package advisory, otherwise the CVSS v3 base score band. Malicious packages are critical.


`critical` Ubuntu critical, Red Hat Critical, or a CVSS base score of 9.0 or higher.
`high` Ubuntu high, Red Hat Important, Debian high, or a CVSS base score from 7.0.
`medium` Ubuntu medium, Red Hat Moderate, Debian medium, or a CVSS base score from 4.0.
`low` Ubuntu low, Red Hat Low, Debian low, or a CVSS base score below 4.0.
`negligible` Ubuntu negligible or Debian unimportant: no practical impact on the distribution's builds.
`unknown` Not rated yet.

AgentRelease

version

string · required

Stable semantic version.

Example: 1.2.3

tag

string · required

Git tag of the release.

Example: v1.2.3

url

string | null · required

Release notes on GitHub, null for a release added by hand.

Example: https://github.com/chieftools/serverchief-agent/releases/tag/v1.2.3

is_latest

boolean · required

Whether this is the newest release, the version an agent update installs.

published_at

string · required

ISO 8601 timestamp of the publication.

rollout_starts_at

string · required

ISO 8601 timestamp after which the release is rolled out automatically, 24 hours after its publication by default.

AgentUpdateResult

string

The code an agent reports in the result of an update_agent command, see "Agent updates" in the agent protocol.


`updated` The target version is installed and running.
`install_failed` The package manager failed, the previous version is still installed.
`readiness_failed_rolled_back` The new version did not become ready, the previous version was reinstalled and runs again.
`rollback_failed` The new version did not become ready and reinstalling the previous version failed too.
`target_unavailable` The package repository does not offer the target version.
`rollback_unavailable` The package repository does not offer the installed version, which a rollback needs, so the update was not attempted.
`package_manager_busy` Another process held the package manager lock for an hour.
`unsupported_install` The agent was not installed from the Server Chief package and repository.

Alert

id

string · required

Formatted alert ID.

Example: alert_01j8q8zk2f4m6n7p9r1s3t5v7x

status

AlertStatus · required

firing until two evaluations in a row no longer breach the rule, then resolved.

object · required

The server the alert is about.

rule_id

string | null · required

Formatted ID of the rule that raised it, null once the rule was deleted.

Example: rule_01j8q8zk2f4m6n7p9r1s3t5v7x

rule_description

string · required

What the rule said when the alert fired.

Example: Disk space used above 90% for 10 minutes

metric

AlertMetric · required

What a metric alert rule watches. Each reads one or more stored metrics (see the metrics protocol catalog) and combines the samples of one moment into a value in the unit people set thresholds in: load_per_core divides the 5-minute load by the number of cores, disk_operations adds reads and writes.

condition

AlertCondition · enum · required

Enum values:

above

below

duration_minutes

integer · required

instance

string | null · required

The mount point, disk or interface, null for a server-wide value.

Example: /var

unit

string · enum · required

Unit of the values, such as %, Mbit/s or minutes. Empty for a plain number.

Enum values:

Mbit/s

MB/s

IOPS

packets/s

per second

minutes

Example: %

baseline_value

number | null · required

The normal level the value was compared to when the alert fired, null for a fixed threshold.

Example: 120.5

threshold_value

number | null · required

The value the metric had to stay above or below when the alert fired, null for alerts from before it was kept.

Example: 90

value

number · required

The newest value of the rule's window while it fired.

Example: 93.2

peak_value

number · required

The worst value while it was firing: the highest for above rules, the lowest for below rules.

Example: 95.1

description

string · required

The alert in words.

Example: Disk space used on /var is 93.2%

fired_at

string · required

ISO 8601 time the rule fired.

resolved_at

string | null · required

ISO 8601 time the alert resolved, null while it fires.

closed_reason

string | null · required

Why it closed without the metric recovering, null when it recovered or still fires.

AlertBaseline

string

The normal level a metric alert rule compares to instead of a fixed value. time_of_day averages the metric over the same time of day, half an hour either side, on each of the past seven days, so daily busy hours and nightly jobs count as normal.

AlertCondition

string · enum

Enum values:

above

below

AlertFiredEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A metric alert rule fired.

Enum values:

alert.fired

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

AlertMetric

string

AlertResolvedEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A firing alert resolved.

Enum values:

alert.resolved

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

AlertResolvedReason

string

Why a metric alert closed, sent as data.reason of the alert.resolved webhook.


`recovered` The metric stayed within the rule for two checks in a row, the only reason the problem went away.
`out_of_scope` The rule no longer covers the server, or the server stopped collecting metrics.
`rule_changed` Someone changed the rule, alerts it opens from now on follow the new rule.
`rule_disabled` Someone turned the rule off.
`rule_deleted` Someone deleted the rule.

AlertRule

id

string · required

Formatted alert rule ID.

Example: rule_01j8q8zk2f4m6n7p9r1s3t5v7x

metric

AlertMetric · required

What the rule watches.

condition

AlertCondition · enum · required

Enum values:

above

below

threshold

number · required

Threshold in the metric's unit, or for a baseline rule the percentage above or below the normal level.

Example: 90

required

minimum_difference

number | null · required

For a baseline rule: how much the value must at least differ from normal, in the metric's unit. Null for any difference.

Example: 10

unit

string · enum · required

Unit of the threshold and alert values, such as %, Mbit/s or minutes. Empty for a plain number.

Enum values:

Mbit/s

MB/s

IOPS

packets/s

per second

minutes

Example: %

duration_minutes

integer · required

Minutes the metric must stay above or below the threshold (or the normal level) before the rule fires.

Example: 10

scope

AlertScope · required

all for every server of the team, tag for the servers with a tag, servers for the chosen servers.

exclude

boolean · required

For tag and servers rules: watch the servers without the tag, or all servers except the chosen ones.

required

object[] · required

The chosen servers of a servers rule, empty for other rules.

instance

string | null · required

The mount point, disk or interface the rule watches, null for all mount points or the host total of disks and interfaces.

Example: /var

enabled

boolean · required

Whether the rule is evaluated. Turning it off closes its open alerts.

description

string · required

The rule in words.

Example: Disk space used above 90% for 10 minutes

scope_description

string · required

Where the rule applies, in words.

Example: Servers tagged production

firing_alerts_count

integer · required

Alerts of the rule that are firing.

Example: 1

created_at

string · required

ISO 8601 creation timestamp.

updated_at

string · required

ISO 8601 last-update timestamp.

AlertScope

string

Which of the team's servers a metric alert rule watches. A tag or server rule can also exclude them: all servers without the tag, or all servers except the chosen ones.

AlertStatus

string

Application

id

string · required

Formatted application ID.

Example: application_01j8q8zk2f4m6n7p9r1s3t5v7x

path

string · required

The application root, the directory at or above a document root with its manifests or WordPress core, through symbolic links such as a deploy's current/.

Example: /home/forge/shop.example.com/current

kind

ApplicationKind · required

What the application is: the first of WordPress, Laravel and Symfony that matches, else a Composer or npm project.

version

string | null · required

The WordPress, Laravel (laravel/framework) or Symfony (symfony/http-kernel) version, null for other kinds or when it cannot be read.

Example: 11.9.2

end_of_life

boolean · required

Whether the WordPress, Laravel or Symfony release is past its end of life according to endoflife.date.

end_of_life_at

string | null · required

Date the release reaches or reached its end of life, null when endoflife.date has no date.

Example: 2026-03-12

latest_version

string | null · required

The latest WordPress release, null for other kinds or while it is unknown.

Example: 6.8.3

outdated

boolean | null · required

Whether WordPress is older than its latest release, null for other kinds or when it cannot be told.

sites

string[] · required

Names of the sites it serves, sorted.

Example: ["shop.example.com","www.shop.example.com"]

owner

string | null · required

The Plesk subscription, DirectAdmin user or home directory owner of its first site, null when unknown.

Example: forge

lockfiles

string[] · required

The lockfiles read at the application root.

Example: ["composer.lock","package-lock.json"]

packages_count

integer · required

Composer and npm packages of its lockfiles, development dependencies included.

Example: 214

plugins_count

integer · required

WordPress plugins, must-use plugins included.

Example: 15

themes_count

integer · required

WordPress themes.

Example: 2

truncated

boolean · required

Whether packages, plugins or themes were left out because the agent's limits were reached.

detected_at

string · required

ISO 8601 timestamp the agent first reported the application.

object

The server the application runs on.

open_vulnerabilities_count

integer

Open vulnerabilities of packages it needs in production.

Example: 3

malicious_packages_count

integer

Open malicious packages, in production or development dependencies.

Example: 0

ApplicationEcosystem

string

Where an application's package comes from: its Composer or npm lockfile, or a WordPress install's plugin and theme directories. wordpress-core is WordPress itself, never a package row: vulnerabilities of a WordPress release carry it.

ApplicationKind

string

What a web application is, from the agent's applications dataset: the first of WordPress, Laravel and Symfony that matches, else a Composer or npm project.

ApplicationPackage

ecosystem

ApplicationEcosystem · required

composer or npm for a package of a lockfile, wordpress-plugin or wordpress-theme for a WordPress plugin or theme.

name

string · required

The package name, or a plugin's or theme's directory (its slug).

Example: guzzlehttp/guzzle

version

string | null · required

The installed version, null when a plugin or theme header names none.

Example: 7.9.2

title

string | null · required

A plugin's or theme's name from its header, null for packages.

Example: Akismet Anti-spam

direct

boolean · required

Whether composer.json or package.json requires the package itself rather than another package.

dev

boolean · required

Whether only development dependencies need the package.

must_use

boolean · required

Whether the plugin is a must-use plugin, which WordPress always loads.

parent

string | null · required

The parent theme of a child theme.

Example: twentytwentyfour

latest_version

string | null · required

The newest stable release on Packagist, npm or WordPress.org, null when the registry does not have the package or it was not looked up yet.

Example: 7.9.2

latest_released_at

string | null · required

ISO 8601 timestamp the latest stable release was published, when the registry tells.

outdated

boolean | null · required

Whether the installed version is older than the latest stable release, null when it cannot be told.

ApplicationVulnerability

vulnerability_id

string · required

The CVE ID, or the advisory ID for an advisory that names no CVE, such as a malicious package's MAL ID. A CVE that GitHub and Drupal both publish is listed once.

Example: CVE-2022-31090

advisory_id

string · required

The most severe advisory covering it.

Example: GHSA-25mq-v84q-4j7r

advisory_ids

string[] · required

Every advisory that covers this vulnerability for the package: GitHub (GHSA), Drupal and malicious package advisories from OSV.dev, and Wordfence Intelligence's for WordPress (WORDFENCE- and the record's ID).

Example: ["GHSA-25mq-v84q-4j7r"]

advisory_url

string · required

The page of the most severe advisory. Wordfence's records are copyright Defiant Inc. and licensed on the condition that copies link to the record and reproduce the copyright and license, see https://www.wordfence.com/wordfence-intelligence-terms-and-conditions/.

Example: https://github.com/advisories/GHSA-25mq-v84q-4j7r

summary

string | null · required

Summary of the deciding advisory, or the start of its description.

Example: CURLOPT_HTTPAUTH option not cleared on change of origin

ecosystem

ApplicationEcosystem · required

composer, npm, wordpress-plugin, wordpress-theme, or wordpress-core for WordPress itself (package wordpress).

package

string · required

installed_version

string · required

fixed_version

string | null · required

The lowest release that fixes it above the installed version, null without a fix and always for a malicious package.

Example: 7.4.5

fix_status

VulnerabilityFixStatus · required

available when a fixed release exists, none without one.


`available` The package manager offers an update to the fixed version or later, installing pending updates fixes it.
`reboot` A newer installed kernel fixes it, rebooting into that kernel does.
`released` A fix was released, but the server's package manager does not offer it yet: it waits for a point release (Debian's `proposed-updates`), its package lists are stale, or the fix needs a subscription such as Ubuntu Pro (ESM).
`none` The distribution has not released a fix for the server's release.

severity

AdvisorySeverity · required

GitHub's or Wordfence's rating of the advisory, otherwise the CVSS v3 band. Malicious packages are critical.


`critical` Ubuntu critical, Red Hat Critical, or a CVSS base score of 9.0 or higher.
`high` Ubuntu high, Red Hat Important, Debian high, or a CVSS base score from 7.0.
`medium` Ubuntu medium, Red Hat Moderate, Debian medium, or a CVSS base score from 4.0.
`low` Ubuntu low, Red Hat Low, Debian low, or a CVSS base score below 4.0.
`negligible` Ubuntu negligible or Debian unimportant: no practical impact on the distribution's builds.
`unknown` Not rated yet.

cvss_score

number | null · required

Highest CVSS v3 base score of the advisories, null without a CVSS v3 vector.

Example: 7.7

malicious

boolean · required

Whether the package was published with malicious code: remove it and check the server.

dev

boolean · required

Whether only development dependencies need the package. Such vulnerabilities are not counted or alerted on.

known_exploited

boolean · required

Whether CISA lists the CVE in its Known Exploited Vulnerabilities catalog.

known_exploited_at

string | null · required

Date CISA added the CVE to its Known Exploited Vulnerabilities catalog, null when it is not listed.

Example: 2026-10-27

epss_score

number | null · required

FIRST's EPSS score: the probability of exploitation activity in the next 30 days, 0 to 1.

Example: 0.01947

epss_percentile

number | null · required

How the EPSS score ranks among all scored CVEs, 0 to 1.

Example: 0.83121

public_exploit

boolean · required

Whether Metasploit, Nuclei or Exploit-DB has a public exploit of the CVE, so attacking it takes little skill.

metasploit_module

string | null · required

Full name of a Metasploit Framework exploit or auxiliary module attacking the CVE, null when there is none.

Example: exploit/linux/http/magento_xxe_to_glibc_buf_overflow

nuclei_template

string | null · required

Path of a Nuclei template detecting the CVE in ProjectDiscovery's nuclei-templates repository, null when there is none.

Example: http/cves/2021/CVE-2021-44228.yaml

exploit_db_id

integer | null · required

ID of an exploit or proof of concept of the CVE on Exploit-DB, null when there is none.

Example: 50973

first_seen_at

string · required

ISO 8601 timestamp the vulnerability was first found in the application.

resolved_at

string | null · required

ISO 8601 timestamp the vulnerability was resolved, null while it is open.

resolved_version

string | null · required

Version of the package when the vulnerability was resolved, null when the package was removed or it is open.

Example: 7.4.5

CertificateIssue

string

A check a certificate fails, computed on ingest by Services\Certificates\Checks.


`expiring_unmanaged` Expires within the warning window, or expired, and no renewal automation was found.
`renewal_missing` Issued by certbot or acme.sh, but no timer or cron job renews it.
`staging_ca` Issued by a staging CA such as Let's Encrypt staging, which browsers do not trust.
`self_signed_public` Self-signed and used by a site with a public domain name.
`incomplete_chain` The leaf does not verify to a trusted root with the intermediates found next to it.
`weak_key` An RSA key below 2048 bits or an EC curve below P-256.
`names_not_covered` Names of a site using it that the certificate does not cover.
`duplicate` Another certificate on the server covers the same names and is newer.

CertificateIssueDetails

issue

CertificateIssue · required

The check the certificate fails.


`expiring_unmanaged` Expires within the warning window, or expired, and no renewal automation was found.
`renewal_missing` Issued by certbot or acme.sh, but no timer or cron job renews it.
`staging_ca` Issued by a staging CA such as Let's Encrypt staging, which browsers do not trust.
`self_signed_public` Self-signed and used by a site with a public domain name.
`incomplete_chain` The leaf does not verify to a trusted root with the intermediates found next to it.
`weak_key` An RSA key below 2048 bits or an EC curve below P-256.
`names_not_covered` Names of a site using it that the certificate does not cover.
`duplicate` Another certificate on the server covers the same names and is newer.

severity

CertificateIssueSeverity · required

How urgent it is.


`high` Visitors or mail clients get errors now or soon: an expiring certificate nobody renews, an untrusted CA.
`medium` Some clients fail or the certificate is weaker than it should be.
`low` Housekeeping, nothing breaks.

label

string · enum · required

Enum values:

Expiring, not renewed

Renewal missing

Staging CA

Self-signed on a public site

Incomplete chain

Weak key

Names not covered

Duplicate

Example: Weak key

explanation

string · enum · required

What is wrong and what to do about it.

Enum values:

The certificate expires soon or expired, and no certbot, acme.sh or panel renewal was found for it. Renew it by hand or set up automatic renewal.

The certificate was issued with certbot or acme.sh, but no timer or cron job runs the renewal, so it will expire. Enable certbot.timer or the acme.sh cron job.

The certificate comes from a staging CA, which browsers and mail clients do not trust. Issue it again against the production CA.

A site with a public domain name serves a self-signed certificate, so visitors get a certificate warning. Use a certificate from a public CA such as Let's Encrypt.

The intermediate certificates next to the certificate do not lead to a trusted root, so some clients reject it. Configure the full chain file.

The key is weaker than an RSA 2048-bit or P-256 key, which clients may reject. Issue it again with a stronger key.

A site using the certificate answers to names the certificate does not cover, visitors on those names get a certificate warning. Add the names to the certificate.

A newer certificate on the server covers the same names. This one is probably left over and can be removed.

Example: The key is weaker than an RSA 2048-bit or P-256 key, which clients may reject. Issue it again with a stronger key.

CertificateIssueSeverity

string


`high` Visitors or mail clients get errors now or soon: an expiring certificate nobody renews, an untrusted CA.
`medium` Some clients fail or the certificate is weaker than it should be.
`low` Housekeeping, nothing breaks.

CertificateManager

string

The tool that issued and renews a certificate, from the agent's managed_by.tool.

CertificateRenewal

string

The renewal automation the agent found for a certificate, from managed_by.renewal.


`timer` A systemd timer, such as certbot.timer.
`cron` A cron job, such as `certbot renew` or `acme.sh --cron`.
`panel` The hosting panel renews it.
`none` No renewal automation was found.

CertificateUsage

string

What uses a certificate, from the agent's used_by[].kind.


`site` A site, its ref is the vhost key `source/name`.
`postfix`
`dovecot`
`exim`
`panel` The hosting panel's own interface.
`other` Another service, named by its ref.

CertificateUsedBy

kind

CertificateUsage · required

What uses the certificate.


`site` A site, its ref is the vhost key `source/name`.
`postfix`
`dovecot`
`exim`
`panel` The hosting panel's own interface.
`other` Another service, named by its ref.

ref

string · required

The vhost key (source/name) for a site, the service name otherwise.

Example: apache/shop.example.com

site_url

string | null · required

The site's page in Server Chief, null for services.

Example: https://server.chief.app/team/acme/sites/01j8q8zk2f4m6n7p9r1s3t5v7x/shop.example.com

CreateInstallCommandRequest

single_use

boolean

Whether the command adds one server, or any number of servers until it expires.

Default: true

valid_for_hours

integer · min: 1 · max: 24

Hours the command can add servers, at most 24.

Default: 1

description

string | null · maxLength: 255

What the command is for, shown with the active install commands.

Example: Web servers in Frankfurt

tags

string[] · maxItems: 50 · unique

Tags of the team every added server gets, by formatted ID or by name.

Example: ["production","tag_01j8q8zk2f4m6n7p9r1s3t5v7x"]

CreateWebhookEndpointRequest

url

string · uri · maxLength: 2048 · required

HTTPS URL that receives the events, it must resolve to a public address.

Example: https://example.com/webhooks/chief

events

string[] · minItems: 1 · unique · required

Event types the endpoint receives, * for every event including types added later.

Enum values:

server.created

server.enrolled

server.updated

server.deleted

server.offline

server.online

server.reboot_stalled

Example: ["server.offline","server.online"]

description

string | null · maxLength: 255

What the endpoint is for, shown in the dashboard.

Example: Paging

InstallCommand

id

string · required

Formatted install command ID.

Example: install_01j8q8zk2f4m6n7p9r1s3t5v7x

status

InstallCommandStatus · required

active while it can add servers, used once a single-use command added its server, or expired or revoked.

description

string | null · required

single_use

boolean · required

Whether it adds one server, or any number of servers until it expires.

servers_added

integer · required

Servers added with it.

Example: 2

ServerTag[] · required

Tags every added server gets.

expires_at

string · required

ISO 8601 timestamp after which it no longer adds servers.

last_used_at

string | null · required

ISO 8601 timestamp of the last server it added, null before the first.

revoked_at

string | null · required

ISO 8601 timestamp it was revoked, null unless revoked.

created_at

string · required

ISO 8601 creation timestamp.

token

string | null

One-time view of the enrollment token, only in the response that creates the command. Store it or run the command right away.

Example: scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE

install_command

string | null

Shell command that installs the agent and adds the server, run as root on each server. Only in the response that creates it.

Example: curl -fsSL https://pkg.server.chief.app/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE

InstallCommandStatus

string

InventoryDataset

string

Inventory datasets readable as the agent reported them. Packages, sites, certificates and repositories have their own paginated endpoints instead.


`system` Hostname, operating system, kernel, virtualization, boot time, timezone and PHP builds.
`hardware` CPU, memory, swap, disks and file systems.
`storage` Software RAID arrays with their members, ZFS pools with their vdevs, scrubs and volumes, and the state of NVMe and SCSI disks.
`network` Network interfaces, addresses and default routes.
`resolvers` Nameservers and search domains.
`cloud` Cloud provider, region and instance type from the provider's metadata service.
`updates` Pending updates, whether a reboot is required and when the package lists were refreshed.

MetricPoint

at

string · required

ISO 8601 start of the bucket.

avg

number · required

Average of the bucket's samples.

Example: 12.5

min

number · required

Lowest sample of the bucket.

max

number · required

Highest sample of the bucket.

MetricSeries

metric

string · required

Stored metric name.

Example: cpu.user

instance

string | null · required

The mount point, disk or interface, null for a server-wide value or the host total of disks and interfaces.

Example: eth0

required

MetricPoint[] · required

Buckets oldest first: the average, lowest and highest sample of each. Buckets without samples are left out.

MetricUnit

string

The unit a stored metric is sent in (metrics protocol, "Metric catalog").

MetricValue

metric

string · required

Stored metric name. New metrics may be added.

Example: fs.used_pct

instance

string | null · required

The mount point, disk or interface, null for a server-wide value or the host total of disks and interfaces.

Example: /var

required

value

number · required

at

string · required

ISO 8601 time of the sample.

MetricsResumedEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A server delivers metrics again.

Enum values:

metrics.resumed

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

MetricsStalledEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

An online server stopped delivering metrics.

Enum values:

metrics.stalled

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

PackageOriginKind

string

Where an installed package version comes from, derived from its origins and the server's repositories.


`distro` A distribution repository offers the installed version, security advisories cover it.
`third_party` Only third-party repositories offer it, distribution advisories do not cover it.
`none` No configured repository offers it: a manually installed package, a removed repository or a superseded version.
`unknown` The agent could not tell, or the repositories are not known yet.

PackageUpgradeResult

string

The code an agent reports in the result of an upgrade_packages command, see "Package updates" in the agent protocol.


`upgraded` The updates of the scope were installed.
`nothing_to_upgrade` No update of the scope was pending.
`upgrade_failed` The package manager failed, the output shows why. Some updates may have been installed.
`dpkg_interrupted` dpkg reports an interrupted install, which someone has to finish with `dpkg --configure -a` first.
`security_unavailable` The repositories have no security metadata, so security updates cannot be told apart.
`package_manager_busy` A package manager held its lock for an hour.
`too_late` The updates were not started before the `not_after` deadline, such as the end of a maintenance window.
`disabled` The server's operator turned installing updates off with `serverchief disable upgrade_packages`.
`unsupported` The agent cannot install updates on this server, the detail says why.

PackageUpgradeScope

string

Which pending updates an upgrade_packages command installs, see "Package updates" in the agent protocol.


`security` The pending updates the agent marks as security updates.
`all` Every pending update.

RebootResult

string

The code an agent reports in the result of a reboot command, see "Reboots" in the agent protocol.


`rebooted` The server rebooted and the agent started again.
`disabled` The server's operator turned reboots off with `serverchief disable reboot`.
`unsupported` The agent cannot reboot this server, the detail says why.
`package_manager_busy` A package manager held its lock for 15 minutes, the server was not rebooted.
`reboot_failed` Scheduling the reboot failed, the output shows why.
`not_rebooted` The reboot was scheduled but the server did not reboot within 10 minutes, someone may have cancelled it.
`too_late` The reboot was not started before its `not_after` deadline, such as the end of a maintenance window.
`not_required` A reboot only when required found the server did not need one, so it did not reboot.
`required_unknown` A reboot only when required could not tell whether the server needs one, so it did not reboot.

RefreshServerRequest

datasets

array | null · minItems: 1 · unique

Datasets to collect, or null for every enabled dataset.

Enum values:

applications

certificates

cloud

hardware

network

packages

repositories

resolvers

Example: ["packages","updates"]

RemoteAction

string

An action that changes the server, which its operator can turn off on the server with serverchief disable <name>, see "Operator opt-out" in the agent protocol. The agent then lists it in capabilities.disabled.


`reboot` Reboot the server.
`upgrade_packages` Install package updates, the agent's own package first.

ReplaceServerTagsRequest

tags

string[] · maxItems: 50 · unique · required

The complete set of tags, by formatted ID or by name. Tags of the server missing from the list are detached, an empty list removes every tag.

Example: ["production","web"]

RepositoryIssue

string

A check an enabled package repository fails, computed on ingest by Services\Repositories\Checks.


`insecure_trusted` apt `[trusted=yes]`: signatures are not checked at all.
`unsigned` rpm `gpgcheck=0`: package signatures are not checked.
`plain_http` Fetched over plain HTTP. Signed indexes still protect the content, but not against replaying old indexes or watching what is installed.
`eol_mirror` An archive of an end-of-life release, which receives no updates. Informational.

RepositoryIssueDetails

issue

RepositoryIssue · required

The check the repository fails.


`insecure_trusted` apt `[trusted=yes]`: signatures are not checked at all.
`unsigned` rpm `gpgcheck=0`: package signatures are not checked.
`plain_http` Fetched over plain HTTP. Signed indexes still protect the content, but not against replaying old indexes or watching what is installed.
`eol_mirror` An archive of an end-of-life release, which receives no updates. Informational.

informational

boolean · required

Whether it only informs, such as an end-of-life archive, and is not counted as a problem.

label

string · enum · required

Enum values:

Trusted without signature

Signature check off

Plain HTTP

End-of-life archive

Example: Trusted without signature

explanation

string · enum · required

What is wrong and what to do about it.

Enum values:

The repository is marked trusted=yes, so apt installs its packages without checking any signature. Import the vendor's key and use signed-by instead.

gpgcheck=0 turns off package signature checks, anyone who can tamper with the download can install code. Import the vendor's key and set gpgcheck=1.

Packages are downloaded over plain HTTP. Signatures still protect them, but the network sees what is installed and can hold back updates. Use the https URL when the mirror offers one.

The repository is an archive of an end-of-life release, which no longer receives security updates. Upgrade the release.

Example: The repository is marked trusted=yes, so apt installs its packages without checking any signature. Import the vendor's key and use signed-by instead.

RepositoryVendorKind

string

Who publishes a package repository, from the vendor classification in serverchief.repositories.vendors.


`distro` The distribution's own archives, security advisories cover their packages.
`third_party` Anyone else: Sury, NodeSource, Docker, PPAs, a vendor's own repository or an unknown host.

ResendWebhookEventRequest

endpoint

string · required

ID of the endpoint to send the event to. It gets the event even when it did not receive it before, or does not subscribe to its type.

Example: webhook_01m6v2nkcfd8n7hg5r9t5k0ys6

RotateWebhookSecretRequest

replace_previous

boolean

Rotate even though the secret from the last rotation still signs deliveries. That secret stops signing right away, receivers that only know it start rejecting deliveries.

Default: false

SaveAlertRuleRequest

metric

string · enum · required

What the rule watches.

Enum values:

cpu_used

cpu_iowait

cpu_steal

load_per_core

memory_used

swap_used

disk_space_used

inodes_used

Example: disk_space_used

condition

AlertCondition · enum · required

Fire when the metric stays above or below the threshold.

Enum values:

above

below

Example: above

threshold

number · min: 0 · max: 1000000000 · required

Threshold in the metric's unit: a percentage for percentages, Mbit/s for network traffic, MB/s for disk throughput and minutes for uptime. For a baseline rule, the percentage above or below the normal level instead.

Example: 90

duration_minutes

integer · min: 1 · max: 1440 · required

Minutes the metric must stay above or below the threshold, 1 to 1440.

Example: 10

baseline

string | null · enum

Compare to the metric's normal level instead of a fixed value: time_of_day is the average at the same time of day over the past week. Null for a fixed threshold. Not for disk space, inodes and uptime.

Enum values:

time_of_day

Default: null

minimum_difference

number | null · min: 0 · max: 1000000000

For a baseline rule: how much the value must at least differ from normal, in the metric's unit, so a metric that is normally close to zero does not alert on a small change. Null for any difference.

Example: 10

scope

string · enum

Which of the team's servers the rule watches: all, the servers with tag, or the chosen servers.

Enum values:

all

tag

servers

Default: all

exclude

boolean

For tag and servers rules: watch the servers without the tag, or all servers except the chosen ones.

Default: false

tag

string | null · maxLength: 64

Formatted ID of one of the team's tags, required for tag rules.

Example: tag_01j8q8zk2f4m6n7p9r1s3t5v7x

servers

string[] · maxItems: 500

Formatted IDs of the team's servers, required for servers rules.

Example: ["server_01j8q8zk2f4m6n7p9r1s3t5v7x"]

instance

string | null · maxLength: 128 · pattern: ^[^\x00-\x1F\x7F]*$

The mount point, disk or interface to watch, for metrics that have them. Without one, disk space and inode rules watch every mount point separately, and disk and network rules the host total.

Example: /var

enabled

boolean

Whether the rule is evaluated. Turning it off closes its open alerts.

Default: true

SaveServerRequest

name

string · maxLength: 255 · required

Human-readable server name.

Example: web-01

hostname

string | null · maxLength: 255

Hostname of the server, or null to clear it.

Example: web-01.example.com

object

Metadata to merge into the server's metadata. Keys are strings of up to 40 characters without [, ], ", \ or ->, values strings of up to 500 characters, and a server has at most 50 keys. Keys starting with serverchief: are read-only system metadata: they are returned in responses, ignored in write requests and do not count towards the limit.

To remove a key, set its value to an empty string. To remove all metadata, send an empty object: {}.

Example: {"customer":"acme","environment":"production"}

tags

string[] · maxItems: 50 · unique

Replace the server's tags with these tags of the team, by formatted ID or by name.

Example: ["production","tag_01j8q8zk2f4m6n7p9r1s3t5v7x"]

object

Override detected location fields, merged into the current overrides. A null field clears its override and falls back to the detected value, null clears every override.

object

Whether the agent refreshes the package lists (apt-get update, yum/dnf makecache) on its own, it never installs packages. Null resets the setting to the default.

object

Whether the agent is updated automatically when a new release has soaked. Null follows the team setting.

SaveTagRequest

name

string · maxLength: 64 · pattern: ^[\pL\pN][\pL\pN _.:… · required

Tag name, unique within the team. Letters, digits, spaces and . _ - : /, starting with a letter or digit.

Example: production

color

string · enum

Colour of the tag in the dashboard.

Enum values:

zinc

red

orange

amber

green

teal

sky

blue

Default: zinc

Server

id

string · required

Formatted server ID.

Example: server_01j8q8zk2f4m6n7p9r1s3t5v7x

name

string · required

hostname

string | null · required

Hostname of the server, or null when it is not known yet.

Example: web-01.example.com

TeamReference · required

The team that owns the server, installed its agent and is billed for it.

access

TeamAccess · required

owner for the team's own servers, viewer for a server shared with the team through a tag. Viewers cannot change the server.


`owner` The team owns the server or tag: it manages it, and owns and is billed for servers.
`viewer` Shared with the team through a tag: the team can view but not change it.

ServerTag[] · required

Tags of the server the team can see: all tags for the owner, the shared tags for a viewer.

object · required

Custom key/value metadata, one map per server shared with every team that can see it. Keys starting with serverchief: are read-only system metadata.

status

ServerStatus · required

Agent status: pending until the agent enrolls, then active, or offline after 15 minutes without contact.


`pending` Created in the dashboard, the agent has not enrolled yet.
`active` The agent enrolled and reported in within the offline threshold.
`offline` The agent has not reported in within the offline threshold.

agent_version

string | null · required

Version of the installed agent, or null before enrollment.

Example: 1.0.0

object · required

The agent and its self-updates.

last_contact_at

string | null · required

ISO 8601 timestamp of the last agent contact, or null when the agent never reported in.

fqdn

string | null · required

Fully qualified domain name reported by the server.

Example: web-01.example.com

os_family

string | null · required

Operating system family.

Example: debian

os_id

string | null · required

Operating system ID from os-release.

Example: ubuntu

os_name

string | null · required

os_version

string | null · required

Full operating system version.

Example: 24.04.1

os_codename

string | null · required

kernel_release

string | null · required

arch

string | null · required

CPU architecture.

Example: amd64

virtualization

string | null · required

Virtualization role and technology, or null on bare metal.

Example: guest/kvm

boot_time

string | null · required

ISO 8601 timestamp of the last boot.

cpu_model

string | null · required

cpu_cores

integer | null · required

Physical CPU cores, or logical CPUs when the core count is unknown.

Example: 4

cpu_threads

integer | null · required

Logical CPUs.

Example: 8

memory_bytes

integer | null · required

Total memory in bytes.

Example: 17179869184

swap_bytes

integer | null · required

Total swap in bytes.

disk_bytes

integer | null · required

Combined size of the non-removable physical disks in bytes, without RAID arrays, ZFS volumes and other devices built on them.

required

storage_unhealthy_since

string | null · required

When the storage stopped being healthy, null while it is healthy.

public_ipv4

string | null · required

Primary public IPv4 address.

Example: 203.0.113.10

public_ipv6

string | null · required

Primary public IPv6 address.

Example: 2001:db8::10

observed_ip

string | null · required

The address the agent's requests come from, used to locate servers behind NAT.

Example: 198.51.100.7

nameservers

array | null · required

Configured DNS resolvers, or null when not reported yet.

ServerAddress[] · required

IP addresses on the server's network interfaces.

is_os_eol

boolean · required

Whether the operating system release is past its end of life according to endoflife.date.

os_eol_at

string | null · required

End-of-life date of the operating system release, or null when unknown.

pending_updates_count

integer | null · required

Number of packages with a pending update, or null before the agent reported updates.

Example: 12

security_updates_count

integer | null · required

Number of pending security updates, or null before the agent reported updates.

Example: 3

reboot_required

boolean | null · required

Whether the server needs a reboot, null when the agent cannot tell.

updates_checked_at

string | null · required

ISO 8601 timestamp of the package manager's metadata cache the update counts are based on, the agent refreshes it when package_metadata_refresh is enabled.

object · required

Whether the agent refreshes the package lists itself (apt-get update, yum or dnf makecache). It never installs, upgrades or removes packages.

ServerSoftware[] · required

Software products detected from the installed packages, one entry per product and major.minor.

provider

string | null · required

Hosting provider slug, such as hetzner, aws, digitalocean, gcp, azure or ovh, from cloud metadata, the network of the server's IP address, or a manual override. New values may be added.

Example: hetzner

city

string | null · required

City derived from the provider region or set manually, IP lookups give no city.

Example: Falkenstein

country

string | null · required

ISO 3166-1 alpha-2 country code.

Example: DE

continent

string | null · required

Continent code: AF, AN, AS, EU, NA, OC or SA.

Example: EU

required

cloud_region

string | null · required

Provider region as reported by the agent, such as fsn1 or eu-central-1.

Example: fsn1

cloud_zone

string | null · required

Provider zone as reported by the agent.

Example: fsn1-dc14

instance_type

string | null · required

Instance type, null where the provider does not expose it.

Example: m6i.large

asn

integer | null · required

Autonomous system number of the server's IP address.

Example: 24940

asn_org

string | null · required

Name of the autonomous system.

Example: Hetzner Online GmbH

object · required

Location fields the owner set manually, they win over detected values. Null fields use the detected value.

vhosts_count

integer | null · required

Number of sites (virtual hosts) on the server, or null before the agent reported them.

Example: 12

certificates_count

integer | null · required

Certificates of the server's sites and services, null before the agent reported them.

Example: 4

certificate_issues_count

integer | null · required

Certificates failing at least one check, null before the agent reported certificates.

Example: 1

repositories

object | null · required

Package repositories and where the installed packages come from, null before the agent reported repositories.

vulnerabilities

object | null · required

Open vulnerabilities from security advisories, each CVE counted once with its highest severity. Null when the server's release has no advisory data (an unsupported or end-of-life release without a feed, such as CentOS 7) or its packages were not matched yet.

required

created_at

string · required

ISO 8601 creation timestamp.

updated_at

string · required

ISO 8601 last-update timestamp.

ServerAddress

interface

string · required

Name of the network interface.

Example: eth0

address

string · required

prefix

integer · required

Prefix length of the network.

Example: 24

family

integer · required

IP version, 4 or 6.

Example: 4

scope

string · required

Scope of the address as classified by the agent, such as public, private, link-local or loopback.

Example: public

ServerCertificate

id

string · required

Formatted certificate ID.

Example: certificate_01j8q8zk2f4m6n7p9r1s3t5v7x

fingerprint

string · required

SHA-256 of the leaf certificate's DER encoding, lowercase hex. Sites link to it by the fingerprint of their certificate.

Example: 3f6c1a9e0b7d4c2a8e5f1b3d7a9c0e2f4b6d8a1c3e5f7b9d0a2c4e6f8b1d3a5c

serial

string | null · required

Serial number, hex.

Example: 04a1b2c3d4e5f60718293a4b5c6d7e8f9a0b

object · required

The subject's common name and organisation.

object · required

The issuer's common name and organisation.

not_before

string | null · required

ISO 8601 timestamp the certificate is valid from.

not_after

string | null · required

ISO 8601 timestamp the certificate expires at.

expired

boolean · required

Whether the certificate has expired.

days_left

integer | null · required

Whole days until the certificate expires, negative once it expired, null without an expiry.

Example: 42

names

string[] · required

DNS names and IP addresses the certificate covers, sorted and in lower case.

Example: ["shop.example.com","www.shop.example.com"]

object · required

The public key.

signature_algorithm

string | null · required

self_signed

boolean · required

Whether the certificate is self-signed.

object · required

The intermediate chain found next to the certificate.

paths

string[] · required

Certificate files the certificate was found in, sorted.

CertificateUsedBy[] · required

Sites and services configured with the certificate.

object · required

The tool that issued the certificate and renews it. Its fields are null when no tool was detected.

CertificateIssueDetails[] · required

The checks the certificate fails, the most severe first.

required

first_seen_at

string · required

ISO 8601 timestamp the certificate was first reported on the server.

url

string · required

The certificate's page in Server Chief.

Example: https://server.chief.app/team/acme/certificates/01j8q8zk2f4m6n7p9r1s3t5v7x

object

The server using the certificate.

ServerChange

id

string · required

Formatted change ID.

Example: change_01jb9a2c3d4e5f6g7h8j9k0m1n

dataset

string · required

Dataset the change belongs to: an inventory dataset, vulnerabilities or agent. New values may be added.

Example: packages

kind

ServerChangeKind · required


`changed` A value was replaced, both old and new are set.
`added` An item appeared, only new is set.
`removed` An item disappeared, only old is set.

subject

string · required

What changed within the dataset: a field path such as os.version_full, a package name, or a site or certificate followed by its changed field.

Example: php8.2-fpm

label

string · required

Readable description of the subject.

Example: Package php8.2-fpm

old

required

Value before the change, null when added. Its shape depends on the dataset and subject.

new

required

Value after the change, null when removed. Its shape depends on the dataset and subject.

detected_at

string · required

ISO 8601 timestamp the change was detected.

ServerChangeKind

string


`changed` A value was replaced, both old and new are set.
`added` An item appeared, only new is set.
`removed` An item disappeared, only old is set.

ServerCommand

id

string · required

Formatted command ID.

Example: command_01jb9a2c3d4e5f6g7h8j9k0m1n

kind

ServerCommandKind · required


`refresh_inventory` Collect the listed datasets, or all enabled ones, now and push whatever changed.
`resync` Send the listed datasets, or all enabled ones, in full on the next push.
`refresh_config` Fetch the agent configuration now.
`update_agent` Install another agent version from the Server Chief package repository, with a rollback when it does not start.
`reboot` Reboot the server in one minute, after waiting for the package manager, unless its operator turned reboots off.
`upgrade_packages` Install the pending package updates, the agent's own package first, unless the operator turned this off.
`disable_capability` Turn a remote action off on the server, only `serverchief enable` on the server turns it on again.

status

ServerCommandStatus · required

Agent status of the command.


`queued` Waiting for a slot: the team already runs as many commands of its kind at once as it may, see `ServerCommandKind::concurrency()`. The agent does not see it yet.
`pending` Waiting for the agent to fetch it.
`delivered` Returned to the agent, not acknowledged yet.
`acknowledged` The agent accepted the command and is working on it.
`succeeded` The agent finished the command successfully.
`failed` The agent reported that the command failed.
`cancelled` Someone cancelled it before the agent fetched it.
`expired` The agent did not acknowledge the command within 24 hours, or reported no result within an hour of acknowledging it (three hours for update_agent and upgrade_packages).

datasets

array | null · required

Datasets the command applies to, or null for every enabled dataset.

version

string | null · required

Agent version an update_agent command installs, null for other kinds.

Example: 1.2.3

detail

string | null · required

Result detail reported by the agent.

update_result

object | null · required

Outcome of an update_agent command, null for other kinds and before the agent reported a result.

reboot_result

object | null · required

Outcome of a reboot command, null for other kinds and before the agent reported a result.

upgrade_result

object | null · required

Outcome of an upgrade_packages command, null for other kinds and before the agent reported a result.

required

created_at

string · required

ISO 8601 creation timestamp.

expires_at

string · required

ISO 8601 timestamp after which an unacknowledged command expires.

finished_at

string | null · required

ISO 8601 timestamp of the agent's result, or null while the command is outstanding.

ServerCommandKind

string


`refresh_inventory` Collect the listed datasets, or all enabled ones, now and push whatever changed.
`resync` Send the listed datasets, or all enabled ones, in full on the next push.
`refresh_config` Fetch the agent configuration now.
`update_agent` Install another agent version from the Server Chief package repository, with a rollback when it does not start.
`reboot` Reboot the server in one minute, after waiting for the package manager, unless its operator turned reboots off.
`upgrade_packages` Install the pending package updates, the agent's own package first, unless the operator turned this off.
`disable_capability` Turn a remote action off on the server, only `serverchief enable` on the server turns it on again.

ServerCommandOrigin

string

Where a command came from, recorded with the user who asked for it.


`panel` Someone asked for it in the web app.
`api` An API or MCP client asked for it.
`system` Server Chief queued it on its own, such as the automatic agent rollout.

ServerCommandStatus

string


`queued` Waiting for a slot: the team already runs as many commands of its kind at once as it may, see `ServerCommandKind::concurrency()`. The agent does not see it yet.
`pending` Waiting for the agent to fetch it.
`delivered` Returned to the agent, not acknowledged yet.
`acknowledged` The agent accepted the command and is working on it.
`succeeded` The agent finished the command successfully.
`failed` The agent reported that the command failed.
`cancelled` Someone cancelled it before the agent fetched it.
`expired` The agent did not acknowledge the command within 24 hours, or reported no result within an hour of acknowledging it (three hours for update_agent and upgrade_packages).

ServerCreatedEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A server was added and waits for its agent.

Enum values:

server.created

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

ServerDeletedEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A server was removed.

Enum values:

server.deleted

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

ServerEnrolledEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A server's agent enrolled for the first time.

Enum values:

server.enrolled

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

ServerEnrollment

token

string · required

One-time enrollment token. It is only returned once, store it or run the install command right away.

Example: scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE

install_command

string · required

Shell command that installs the agent and enrolls it with the token, run it as root on the server.

Example: curl -fsSL https://pkg.server.chief.app/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE

expires_at

string · required

ISO 8601 timestamp after which the token can no longer be used.

ServerInventory

dataset

InventoryDataset · required

Inventory datasets readable as the agent reported them. Packages, sites, certificates and repositories have their own paginated endpoints instead.


`system` Hostname, operating system, kernel, virtualization, boot time, timezone and PHP builds.
`hardware` CPU, memory, swap, disks and file systems.
`storage` Software RAID arrays with their members, ZFS pools with their vdevs, scrubs and volumes, and the state of NVMe and SCSI disks.
`network` Network interfaces, addresses and default routes.
`resolvers` Nameservers and search domains.
`cloud` Cloud provider, region and instance type from the provider's metadata service.
`updates` Pending updates, whether a reboot is required and when the package lists were refreshed.

collected

boolean · required

Whether the agent collects the dataset, false when the team or server turned it off.

received_at

string | null · required

ISO 8601 timestamp of the agent's last report of the dataset, null before the first.

object | null · required

The dataset as the agent reported it, see the agent protocol for its fields. Null before the first report.

ServerLocationSource

string


`agent` Reported by the agent from cloud metadata or DMI, mapped from the provider region.
`ip` Looked up from the server's public or observed IP address in the IPInfo database: provider and country, no city.
`manual` Set by the owner team, it wins over agent and IP data.

ServerMetricSeries

range

string · required

collecting

boolean · required

Whether the server collects metrics: its agent sends them and the owner did not turn them off.

since

string | null · required

ISO 8601 time of the oldest kept sample: a range reaching further back has no buckets before it.

MetricSeries[] · required

One series per metric and instance, sorted by metric and instance.

ServerMetrics

collecting

boolean · required

Whether the server collects metrics: its agent sends them and the owner did not turn them off.

since

string | null · required

ISO 8601 time of the oldest kept sample, or when collection started while there is none yet.

MetricValue[] · required

The newest value of every metric and instance the server sent in the last 10 minutes, by metric name. CPU use is 100 minus cpu.idle.

ServerOfflineEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A server stopped checking in.

Enum values:

server.offline

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

ServerOnlineEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

An offline server checks in again.

Enum values:

server.online

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

ServerPackage

manager

string · required

Package manager, dpkg or rpm.

Example: dpkg

name

string · required

arch

string · required

version

string · required

Installed version as reported by the package manager, including epoch and revision. Version filters compare it like dpkg or rpm.

Example: 1.0.2g-1ubuntu4.20

upstream_version

string · required

Upstream part of the version, without epoch and revision.

Example: 1.0.2g

source

string | null · required

Source package, when it differs from the package name.

Example: util-linux

source_version

string | null · required

Version of the source package, when it differs from the version. Security advisories compare it.

Example: 2.36-9+deb12u4

candidate_version

string | null · required

Version an update would install, or null when the package is up to date.

Example: 1.0.2g-1ubuntu4.21

is_security

boolean · required

Whether the pending update is a security update.

origins

array | null · required

IDs of the server's repositories that offer the installed version, see the server's repositories. Empty when none does, null when the agent could not tell.

Example: ["bookworm:c4a17d93"]

origin_vendor

string | null · required

Vendor slug of the repository the installed version comes from, a distribution repository first, such as debian-security, sury or ppa:ondrej/php. Null without a known origin. New values may be added.

Example: sury

origin_kind

PackageOriginKind · required

distro, third_party (only third-party repositories offer it, distribution advisories are not matched against it), none (no configured repository offers it) or unknown (no origin data).


`distro` A distribution repository offers the installed version, security advisories cover it.
`third_party` Only third-party repositories offer it, distribution advisories do not cover it.
`none` No configured repository offers it: a manually installed package, a removed repository or a superseded version.
`unknown` The agent could not tell, or the repositories are not known yet.

object

The server the package is installed on, only included when searching packages across servers.

ServerRebootStalledEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A server did not come back after a reboot.

Enum values:

server.reboot_stalled

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

ServerRepository

id

string · required

The repository ID the agent reports, as listed in package origins: a suite-prefixed hash for apt, the section name for rpm.

Example: bookworm-security:3f2a9c1e

file

string | null · required

The file defining it.

Example: /etc/apt/sources.list.d/php.list

type

string · required

deb, deb-src or rpm.

Example: deb

enabled

boolean · required

Whether the package manager uses it. Disabled repositories have no issues.

uris

string[] · required

The configured URIs without credentials or query strings, mirror lists prefixed with mirrorlist: or metalink: and keeping their identifying parameters such as repo.

Example: ["https://packages.sury.org/php"]

suite

string | null · required

The apt suite, null for rpm.

Example: bookworm

components

string[] · required

The apt components, empty for rpm.

Example: ["main"]

name

string | null · required

The rpm repository name, null for apt.

Example: Remi's PHP 8.3 RPM repository for Enterprise Linux 9

object · required

How the package manager verifies it.

transport

string | null · required

The scheme of the first URI: https, http, file, cdrom, tor or mirror.

Example: https

packages

integer · required

Installed packages whose installed version this repository offers.

Example: 42

object · required

Who publishes it, classified from the URIs.

RepositoryIssueDetails[] · required

Checks the repository fails, insecure ones first.

first_seen_at

string · required

ISO 8601 timestamp the repository was first reported.

ServerSoftware

product

string · required

Normalised product name, such as php, mysql, mariadb, nginx, apache, openssl, kernel, nodejs, redis or postgresql. New products may be added.

Example: php

version

string · required

Upstream version without epoch or distribution revision, product filters such as php:7.4 match on it.

Example: 7.4.33

package_version

string | null · required

Full version of the package the product was detected from, including epoch and revision: distributions backport security fixes as new revisions of the same upstream version.

Example: 7.4.33-1+ubuntu16.04.1+deb.sury.org+1

manager

string | null · required

Package manager of that package, dpkg or rpm. Null for a PHP build without a package.

Example: dpkg

major

integer · required

minor

integer | null · required

patch

integer | null · required

package

string | null · required

Package the version was derived from, or for a PHP build without a package the directory it is installed in, such as /usr/local/php74.

Example: php7.4-fpm

source

string · required

package when a package provides it, build for PHP built without one, such as a DirectAdmin custombuild or a source build.

Example: package

is_eol

boolean · required

Whether this release cycle is past its end of life according to endoflife.date.

eol_at

string | null · required

End-of-life date of the release cycle, or null when unknown.

ServerStatus

string


`pending` Created in the dashboard, the agent has not enrolled yet.
`active` The agent enrolled and reported in within the offline threshold.
`offline` The agent has not reported in within the offline threshold.

ServerStorageHealthyEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A server's storage is healthy again.

Enum values:

server.storage_healthy

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

ServerStorageUnhealthyEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A RAID array or ZFS pool degraded, or a disk failed.

Enum values:

server.storage_unhealthy

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

ServerTag

id

string · required

Formatted tag ID.

Example: tag_01j8q8zk2f4m6n7p9r1s3t5v7x

name

string · required

color

TagColor · required

ServerUpdatedEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A server's name, metadata, location or settings changed.

Enum values:

server.updated

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

ServerVhost

source

string · required

Where the vhost was found: apache, nginx, plesk or directadmin. A domain served by a panel and its web server appears once per source, all with the same url. New values may be added.

Example: apache

name

string · required

Primary server name, in lower case.

Example: shop.example.com

aliases

string[] · required

Other names the vhost answers to, sorted and in lower case. Wildcards are kept as configured.

Example: ["www.shop.example.com","*.shop.example.com"]

ports

integer[] · required

Ports the vhost listens on, sorted.

Example: [80,443]

ssl

boolean · required

Whether any of the ports serves TLS.

document_root

string | null · required

Document root, or null when the vhost has none.

Example: /var/www/shop/public

php_version

string | null · required

PHP version the site runs as major.minor, or null when unknown or not PHP.

Example: 8.2

php_handler

string | null · required

How PHP runs: fpm, fastcgi, cgi, module or lsapi. New values may be added.

Example: fpm

php

object | null · required

The PHP the site runs with its full installed version, null when unknown or not PHP.

certificate

object | null · required

The TLS certificate the vhost is configured with, null without one.

config_file

string | null · required

Absolute path of the configuration file defining the vhost, null for panel entries without one.

Example: /etc/apache2/sites-enabled/shop.conf

owner

string | null · required

Panel subscription or user owning the site, or on a plain web server the user whose home directory holds the document root, null otherwise.

Example: acme

http2

boolean · required

Whether the vhost offers HTTP/2.

http3

boolean · required

Whether the vhost offers HTTP/3, over a QUIC listener.

https_redirect

boolean · required

Whether plain HTTP requests for the site redirect to HTTPS.

redirect

object | null · required

Where the vhost redirects every request, null when it serves the site itself.

url

string · required

The site's page in Server Chief, shared by every source reporting the site.

Example: https://server.chief.app/team/acme/sites/01j8q8zk2f4m6n7p9r1s3t5v7x/shop.example.com

object

The server hosting the site, only included when searching sites across servers.

ServerVulnerability

vulnerability_id

string · required

The CVE ID, or the advisory ID for an advisory that names no CVE. A CVE that several advisories cover (a Debian CVE record and a DSA) is listed once.

Example: CVE-2023-5363

advisory_id

string · required

The advisory that decided the match, its fixed version applies. The distribution's CVE record when it has one, otherwise the notice that fixes it.

Example: DEBIAN-CVE-2023-5363

advisory_ids

string[] · required

Every advisory of the server's releases that covers this vulnerability for the package.

Example: ["DEBIAN-CVE-2023-5363","DSA-5532-1"]

summary

string | null · required

Summary of the deciding advisory, or the start of its description.

Example: openssl - security update

package

string · required

Source package the advisory names. Debian and Ubuntu advisories name source packages, so one source covers all binary packages built from it.

Example: openssl

binary_package

string | null · required

The installed binary package with the lowest affected version, null once it was removed.

Example: libssl3

installed_version

string · required

Installed version compared with the advisory: the source version when the agent reports it, otherwise the binary version.

Example: 3.0.11-1~deb12u1

fixed_version

string | null · required

First version with the fix, null when the distribution has not released one for the server's release.

Example: 3.0.11-1~deb12u2

fixed_release

string | null · required

Release the fix was published for, such as debian:12 or ubuntu-pro:16.04 for an Ubuntu Pro (ESM) fix. Null without a fix.

Example: debian:12

requires_subscription

boolean · required

Whether the fix needs a subscription, Ubuntu Pro (ESM).

fix_status

VulnerabilityFixStatus · required

available when a pending update installs the fix, released when a fix exists that the package manager does not offer (stale package lists, or a subscription such as Ubuntu Pro), none without a fix.


`available` The package manager offers an update to the fixed version or later, installing pending updates fixes it.
`reboot` A newer installed kernel fixes it, rebooting into that kernel does.
`released` A fix was released, but the server's package manager does not offer it yet: it waits for a point release (Debian's `proposed-updates`), its package lists are stale, or the fix needs a subscription such as Ubuntu Pro (ESM).
`none` The distribution has not released a fix for the server's release.

severity

AdvisorySeverity · required

Severity normalised across distributions: the distribution's rating when it has one, otherwise the CVSS v3 band.


`critical` Ubuntu critical, Red Hat Critical, or a CVSS base score of 9.0 or higher.
`high` Ubuntu high, Red Hat Important, Debian high, or a CVSS base score from 7.0.
`medium` Ubuntu medium, Red Hat Moderate, Debian medium, or a CVSS base score from 4.0.
`low` Ubuntu low, Red Hat Low, Debian low, or a CVSS base score below 4.0.
`negligible` Ubuntu negligible or Debian unimportant: no practical impact on the distribution's builds.
`unknown` Not rated yet.

cvss_score

number | null · required

Highest CVSS v3 base score of the deciding advisories, null without a CVSS v3 vector.

Example: 7.5

known_exploited

boolean · required

Whether CISA lists the CVE in its Known Exploited Vulnerabilities catalog: it is exploited in the wild, fix it first.

known_exploited_at

string | null · required

Date CISA added the CVE to its Known Exploited Vulnerabilities catalog, null when it is not listed.

Example: 2026-10-27

epss_score

number | null · required

FIRST's EPSS score: the probability of exploitation activity in the next 30 days, 0 to 1. Null when the CVE has no score, or for an advisory without a CVE.

Example: 0.04753

epss_percentile

number | null · required

How the EPSS score ranks among all scored CVEs, 0 to 1: 0.95 is a higher score than 95% of them.

Example: 0.91849

public_exploit

boolean · required

Whether Metasploit, Nuclei or Exploit-DB has a public exploit of the CVE, so attacking it takes little skill.

metasploit_module

string | null · required

Full name of a Metasploit Framework exploit or auxiliary module attacking the CVE, null when there is none.

Example: exploit/linux/http/magento_xxe_to_glibc_buf_overflow

nuclei_template

string | null · required

Path of a Nuclei template detecting the CVE in ProjectDiscovery's nuclei-templates repository, null when there is none.

Example: http/cves/2021/CVE-2021-44228.yaml

exploit_db_id

integer | null · required

ID of an exploit or proof of concept of the CVE on Exploit-DB, null when there is none.

Example: 50973

first_seen_at

string · required

ISO 8601 timestamp the vulnerability was first found on the server.

resolved_at

string | null · required

ISO 8601 timestamp the vulnerability was resolved, null while it is open.

resolved_version

string | null · required

Version of the source package when the vulnerability was resolved, null when the package was removed or it is open.

Example: 3.0.11-1~deb12u2

object

The affected server, only included when searching vulnerabilities across servers.

ShareTagRequest

team

string · maxLength: 255 · required

Slug of the team to share the tag with. The team must use Server Chief.

Example: acme

role

string · enum

What the team can do with the tagged servers. viewer is read-only.

Enum values:

viewer

Default: viewer

StorageHealth

string

Health of a server's software RAID arrays, ZFS pools and disks, from the agent's storage dataset.


`healthy` Every array and pool has all its devices without errors and every disk works.
`degraded` An array or pool lost a device or reports device errors, a disk in one failed, or a disk's SMART data says it is failing: the data is still there, but at risk.
`failed` An array or pool stopped, files have permanent errors, or a disk outside any array or pool failed: data is unavailable.

Tag

id

string · required

Formatted tag ID.

Example: tag_01j8q8zk2f4m6n7p9r1s3t5v7x

name

string · required

color

TagColor · required

TeamReference · required

The team that owns the tag and the servers carrying it.

access

TeamAccess · required

owner for the team's own tags, viewer for a tag another team shared with it.


`owner` The team owns the server or tag: it manages it, and owns and is billed for servers.
`viewer` Shared with the team through a tag: the team can view but not change it.

servers_count

integer · required

Number of the owner's servers carrying the tag.

Example: 4

created_at

string · required

ISO 8601 creation timestamp.

updated_at

string · required

ISO 8601 last-update timestamp.

TagColor

string

TagShare

TeamReference · required

The team the tag is shared with.

role

TagShareRole · required

What the team can do with the tagged servers, viewer is read-only.


`viewer` Read-only access to the tagged servers: inventory, packages, software and metadata.

created_at

string · required

ISO 8601 timestamp of when the tag was shared.

TagShareRole

string


`viewer` Read-only access to the tagged servers: inventory, packages, software and metadata.

TeamAccess

string


`owner` The team owns the server or tag: it manages it, and owns and is billed for servers.
`viewer` Shared with the team through a tag: the team can view but not change it.

TeamReference

slug

string · required

Team slug.

Example: acme

name

string · required

UpdateServerTagsRequest

attach

string[] · maxItems: 50 · unique

Tags to attach, by formatted ID or by name. Tags the server already carries are kept.

Example: ["production"]

detach

string[] · maxItems: 50 · unique

Tags to detach, by formatted ID or by name.

Example: ["staging"]

UpdateWebhookEndpointRequest

url

string · uri · maxLength: 2048

HTTPS URL that receives the events, it must resolve to a public address.

Example: https://example.com/webhooks/chief

description

string | null · maxLength: 255

What the endpoint is for, shown in the dashboard. Null removes it.

Example: Paging

events

string[] · minItems: 1 · unique

Event types the endpoint receives, * for every event including types added later. Replaces the current list.

Enum values:

server.created

server.enrolled

server.updated

server.deleted

server.offline

server.online

server.reboot_stalled

Example: ["*"]

UpgradeServerPackagesRequest

scope

string · enum · required

Which pending updates to install: the security updates or every update.

Enum values:

security

all

restart_services

boolean

Restart the services that use updated libraries afterwards, so the updates take effect without a reboot.

Default: true

reboot_if_required

boolean

Reboot the server afterwards when the agent reports that a reboot is required, such as after a kernel update. Needs agent.reboot.available.

Default: false

VulnerabilityFixStatus

string


`available` The package manager offers an update to the fixed version or later, installing pending updates fixes it.
`reboot` A newer installed kernel fixes it, rebooting into that kernel does.
`released` A fix was released, but the server's package manager does not offer it yet: it waits for a point release (Debian's `proposed-updates`), its package lists are stale, or the fix needs a subscription such as Ubuntu Pro (ESM).
`none` The distribution has not released a fix for the server's release.

WebhookAttemptError

string

Why an attempt failed without a usable response, an attempt with a non-2xx response has no error.


`timeout` The endpoint did not answer within 15 seconds.
`connection` The connection failed: DNS, refused, TLS.
`blocked` The URL resolves to a private or reserved address.
`redirect` The endpoint answered with a redirect, which is not followed.

WebhookDelivery

id

string · required

Formatted delivery ID.

Example: delivery_01m6v3f5b0c8z6w4k2t9r7p5n3

endpoint_id

string · required

ID of the endpoint it is sent to.

Example: webhook_01m6v2nkcfd8n7hg5r9t5k0ys6

event_id

string · required

ID of the event it sends.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

event_type

WebhookEventType · required

Type of the event it sends.


`server.created` A server was added and waits for its agent.
`server.enrolled` A server's agent enrolled for the first time.
`server.updated` A server's name, metadata, location or settings changed.
`server.deleted` A server was removed.
`server.offline` A server stopped checking in.
`server.online` An offline server checks in again.
`server.reboot_stalled` A server did not come back after a reboot.
`alert.fired` A metric alert rule fired.
`alert.resolved` A firing alert resolved.
`metrics.stalled` An online server stopped delivering metrics.
`metrics.resumed` A server delivers metrics again.
`server.storage_unhealthy` A RAID array or ZFS pool degraded, or a disk failed.
`server.storage_healthy` A server's storage is healthy again.
`webhook_endpoint.test` A test event sent from the dashboard.

status

WebhookDeliveryStatus · required


`pending` Waiting for its first attempt or for a retry.
`succeeded` The endpoint answered with a 2xx status.
`failed` Every attempt failed.
`cancelled` The endpoint was disabled or deleted before it succeeded.

attempts

integer · required

Attempts made so far, resends included.

next_attempt_at

string | null · required

ISO 8601 time the next automatic attempt is due, null when none is scheduled.

last_attempted_at

string | null · required

ISO 8601 time of the last attempt, null before the first.

last_response_status

integer | null · required

HTTP status of the last response, null before the first attempt or when no response came.

created_at

string · required

ISO 8601 creation timestamp.

WebhookDeliveryAttempt[]

Every attempt with its request and response, oldest first. Only returned for a single delivery.

WebhookDeliveryAttempt

number

integer · required

Number of the attempt within its delivery, from 1.

manual

boolean · required

Whether someone resent it, instead of an automatic attempt.

succeeded

boolean · required

Whether the endpoint answered with a 2xx status in time.

attempted_at

string · required

ISO 8601 time the request was sent.

duration_ms

integer | null · required

How long the request took, null when it could not be sent.

required

error_message

string | null · required

What went wrong, for people.

object · required

response

object | null · required

The endpoint's response, null when none came.

WebhookDeliveryStatus

string


`pending` Waiting for its first attempt or for a retry.
`succeeded` The endpoint answered with a 2xx status.
`failed` Every attempt failed.
`cancelled` The endpoint was disabled or deleted before it succeeded.

WebhookEndpoint

id

string · required

Formatted endpoint ID.

Example: webhook_01m6v2nkcfd8n7hg5r9t5k0ys6

url

string · required

HTTPS URL that receives the events.

Example: https://example.com/webhooks/chief

description

string | null · required

What the endpoint is for.

Example: Paging

array · required

Event types the endpoint receives, * for every event including types added later.

Example: ["server.offline","server.online"]

status

WebhookEndpointStatus · required

Whether deliveries are sent. A disabled endpoint receives nothing until it is enabled again.


`enabled` Receives the events it subscribed to.
`disabled` Receives nothing until someone enables it again, `disabled_reason` tells why.

required

disabled_at

string | null · required

ISO 8601 time the endpoint was disabled, null while it is enabled.

failing_since

string | null · required

ISO 8601 time the endpoint started failing every delivery, null while deliveries succeed. It is disabled after five days.

secret

string | null · required

Signing secret, only set in the response that creates the endpoint or rotates its secret, null otherwise. Store it with your other secrets.

Example: whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw

previous_secret_expires_at

string | null · required

ISO 8601 time until which the secret from before the last rotation still signs deliveries next to the current one, null when only one secret signs.

created_at

string · required

ISO 8601 creation timestamp.

updated_at

string · required

ISO 8601 timestamp of the last change.

WebhookEndpointDisabledReason

string


`manual` Someone disabled it.
`failing` Every delivery failed for five days, so it was disabled automatically.

WebhookEndpointStatus

string


`enabled` Receives the events it subscribed to.
`disabled` Receives nothing until someone enables it again, `disabled_reason` tells why.

WebhookEndpointTestEvent

id

string · required

Identifies the event, the same as the webhook-id header. It stays the same on retries and resends, use it to skip events you processed.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

string · enum · required

A test event sent from the dashboard.

Enum values:

webhook_endpoint.test

timestamp

string · date-time · required

When the event happened, in UTC. It does not change on retries.

api_version

string · required

The version of the payload format.

Example: v1

object · required

WebhookEvent

id

string · required

Formatted event ID, the same as id in the payload and the webhook-id header.

Example: event_01m6v3f5aydrktmzrbpz1pqh7e

type

WebhookEventType · required

Event type.


`server.created` A server was added and waits for its agent.
`server.enrolled` A server's agent enrolled for the first time.
`server.updated` A server's name, metadata, location or settings changed.
`server.deleted` A server was removed.
`server.offline` A server stopped checking in.
`server.online` An offline server checks in again.
`server.reboot_stalled` A server did not come back after a reboot.
`alert.fired` A metric alert rule fired.
`alert.resolved` A firing alert resolved.
`metrics.stalled` An online server stopped delivering metrics.
`metrics.resumed` A server delivers metrics again.
`server.storage_unhealthy` A RAID array or ZFS pool degraded, or a disk failed.
`server.storage_healthy` A server's storage is healthy again.
`webhook_endpoint.test` A test event sent from the dashboard.

api_version

string · required

Version of the payload format.

Example: v1

created_at

string · required

ISO 8601 time the event happened.

object · required

The body every delivery of the event sends, see the event's schema for its fields.

WebhookDelivery[]

The event's deliveries, one per endpoint. Only returned for a single event.

WebhookEventType

string


`server.created` A server was added and waits for its agent.
`server.enrolled` A server's agent enrolled for the first time.
`server.updated` A server's name, metadata, location or settings changed.
`server.deleted` A server was removed.
`server.offline` A server stopped checking in.
`server.online` An offline server checks in again.
`server.reboot_stalled` A server did not come back after a reboot.
`alert.fired` A metric alert rule fired.
`alert.resolved` A firing alert resolved.
`metrics.stalled` An online server stopped delivering metrics.
`metrics.resumed` A server delivers metrics again.
`server.storage_unhealthy` A RAID array or ZFS pool degraded, or a disk failed.
`server.storage_healthy` A server's storage is healthy again.
`webhook_endpoint.test` A test event sent from the dashboard.

WebhookEventTypeDetails

type

WebhookEventType · required

Event type, as type in the payload and in an endpoint's events.


`server.created` A server was added and waits for its agent.
`server.enrolled` A server's agent enrolled for the first time.
`server.updated` A server's name, metadata, location or settings changed.
`server.deleted` A server was removed.
`server.offline` A server stopped checking in.
`server.online` An offline server checks in again.
`server.reboot_stalled` A server did not come back after a reboot.
`alert.fired` A metric alert rule fired.
`alert.resolved` A firing alert resolved.
`metrics.stalled` An online server stopped delivering metrics.
`metrics.resumed` A server delivers metrics again.
`server.storage_unhealthy` A RAID array or ZFS pool degraded, or a disk failed.
`server.storage_healthy` A server's storage is healthy again.
`webhook_endpoint.test` A test event sent from the dashboard.

group

string · required

Heading the event is listed under in the dashboard.

Example: Availability

description

string · required

When the event is sent.

Example: A server stopped checking in.