{ "openapi": "3.1.2", "info": { "title": "Server Chief API v1", "version": "1.0.0", "description": "Query and manage the authenticated team's Server Chief inventory: servers, packages, vulnerabilities, sites, certificates, package sources, tags and agent releases." }, "servers": [ { "url": "https:\/\/server.chief.app\/api\/v1" } ], "tags": [ { "name": "Servers", "description": "Endpoints for managing the servers in the team inventory." }, { "name": "Packages", "description": "Endpoints for searching the packages installed across the team's servers." }, { "name": "Sites", "description": "Endpoints for finding sites (virtual hosts) and their certificates across the team's servers." }, { "name": "Certificates", "description": "Endpoints for the TLS certificates of sites and services across the team's servers, their renewal tooling and issues." }, { "name": "Applications", "description": "Endpoints for the web applications the sites of the team's servers serve: WordPress with its plugins and themes, Laravel, Symfony and other Composer or npm projects, and the vulnerabilities of their packages." }, { "name": "Vulnerabilities", "description": "Endpoints for finding which servers security advisories affect, and the advisories themselves." }, { "name": "Metrics", "description": "Endpoints for the host metrics agents send every minute: CPU, load, memory, swap, file systems, disk I\/O, network, TCP and processes." }, { "name": "Alerts", "description": "Endpoints for the metric alert rules of the team and the alerts they raise. Rules are checked every minute and notify the team when a metric of a server stays above or below a threshold." }, { "name": "Tags", "description": "Endpoints for managing team tags and sharing them read-only with other teams." }, { "name": "Agent releases", "description": "Endpoints for the agent releases servers are updated to." }, { "name": "Webhooks", "description": "Endpoints for the team's webhook endpoints and the events and deliveries sent to them. Webhooks send a signed request to an endpoint when something happens in the team, see the webhooks guide for verifying them." } ], "security": [ { "ctp": [] }, { "openid": [] }, { "ctt": [] } ], "paths": { "\/servers": { "get": { "operationId": "servers.index", "description": "List the servers the authenticated team can see: its own servers and servers other teams shared with it through a tag (access viewer). Optionally filtered with the server search language in q and by exact metadata values.", "summary": "List servers", "tags": [ "Servers" ], "parameters": [ { "name": "q", "in": "query", "description": "Search query in the server search language. Space-separated terms must all match and a leading - negates a term. Free text matches the name, hostname, FQDN, IP or a tag name. Filters: php:8.2 (any product: mysql, mariadb, nginx, apache, openssl, kernel, nodejs, redis, postgresql), php:7.4.33, php:<8.1, php:>=8.2, php:~7.4, php:eol, php:any compare upstream versions, while php:<8.2.35-1+deb12u2 with a revision compares the full package version like dpkg or rpm. pkg:openssl, pkg:linux-image*, pkg:openssl<1.0.2g-1ubuntu4.20, pkg:tzdata>=2024a and pkg:openssl~3.0 always compare like dpkg or rpm per server; a version without a revision covers all of its revisions and a missing epoch is 0. tag:name matches the team's own tags and tags shared with it. os:ubuntu, os:ubuntu@16.04, os:eol, arch:arm64, updates:any, updates:security, updates:none, reboot:required, storage:unhealthy (also degraded, failed or healthy), status:online, status:offline, status:pending, meta:key=value. provider:hetzner, country:DE or country:germany, city:frankfurt or city:none, continent:eu, region:eu (a continent) or region:fsn1 (a provider region). vhost:example.com or domain:example.com match a site by name or alias, cert:expired, cert:expiring, cert:expiring<7d and cert:any match site certificates, vhost-php:7.4 the PHP version sites run; with vhost:, it is the PHP version of that site.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "arch:arm64 php:eol" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "metadata", "in": "query", "description": "Filter by metadata key\/value pairs, every pair must match exactly, for example metadata[customer]=acme.", "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "x-deepObject-style": "qs" } ], "responses": { "200": { "description": "Paginated set of `Server`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Server" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] }, "post": { "operationId": "servers.create", "description": "Add a pending server to the authenticated team's inventory. The response includes a one-time enrollment token and the install command to run on the server; the token is not returned again, issue a new one when it is lost or expired.", "summary": "Create a server", "tags": [ "Servers" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveServerRequest" } } } }, "responses": { "201": { "description": "The server was created.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Server" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:write" ] }, { "ctp": [ "serverchief:servers:write" ] }, { "ctt": [ "serverchief:servers:write" ] } ] } }, "\/packages": { "get": { "operationId": "packages.index", "description": "Find a package across the servers the authenticated team can see, including servers shared with it, optionally limited to a version range compared like dpkg or rpm. The name is found anywhere in package and source package names, best match first: the exact name, names starting with it, names with a part starting with it (`ssl` finds `libssl3`, `fpm` finds `php8.2-fpm`), then names containing it. Names of one or two characters only match from the start. Pass `exact` or a `*` wildcard to match names exactly. Every result includes the server it is installed on.", "summary": "Search packages", "tags": [ "Packages" ], "parameters": [ { "name": "name", "in": "query", "required": true, "description": "Package or source package name, or part of it, best match first. Matched exactly when `exact` is set, or as a pattern when it contains * as a wildcard.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9*][A-Za-z0-9.+_*-]*$", "maxLength": 255 }, "example": "openssl" }, { "name": "exact", "in": "query", "description": "Only return packages named exactly `name`, instead of every package whose name or source package name contains it.", "schema": { "type": "boolean" } }, { "name": "version", "in": "query", "description": "Version constraint, compared like dpkg or rpm for each package's manager: 1.0.2g-1ubuntu4.20 or <1.0.2g-1ubuntu4.20 with a revision compares the full version, 3.0.13 without one matches every revision of 3.0.13, and <, <=, >, >= compare against all of its revisions. ~3.0 or 3.0.x match 3.0 up to 3.1. A missing epoch is 0.", "schema": { "type": [ "string", "null" ], "maxLength": 130 }, "example": "<1.0.2g-1ubuntu4.20" }, { "name": "updates", "in": "query", "description": "Only return packages with a pending update.", "schema": { "type": "boolean" } }, { "name": "origin", "in": "query", "description": "Only return packages from an origin: a repository vendor or alias such as sury, esm or ppa:ondrej\/php, third-party for packages only third-party repositories offer, or none for packages no configured repository offers.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9][a-z0-9._:\\\/+-]*$", "maxLength": 191 }, "example": "third-party" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `ServerPackage`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/ServerPackage" }, { "type": "object", "required": [ "server" ] } ] } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/vhosts": { "get": { "operationId": "vhosts.index", "description": "Find sites across the servers the authenticated team can see, including servers shared with it: which servers host a domain, or which certificates expire soon. Every result includes its server.", "summary": "Search sites", "tags": [ "Sites" ], "parameters": [ { "name": "domain", "in": "query", "description": "Only return sites serving this domain, by name or alias. A host also matches wildcard aliases covering it, and *.example.com matches every subdomain.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "shop.example.com" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cert_expiring_days", "in": "query", "description": "Only return sites whose certificate expires within this many days, including certificates that already expired, sorted by expiry with the soonest first.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 3650 }, "example": 21 } ], "responses": { "200": { "description": "Paginated set of `ServerVhost`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/ServerVhost" }, { "type": "object", "required": [ "server" ] } ] } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/certificates": { "get": { "operationId": "certificates.index", "description": "Find certificates across the servers the authenticated team can see, including servers shared with it: which expire soon, which are not renewed automatically, which certbot or acme.sh plugin issued them, and which fail a check such as a weak key or names a site uses that the certificate does not cover. A certificate used by several sites and services of a server is listed once. Every result includes its server.", "summary": "Search certificates", "tags": [ "Certificates" ], "parameters": [ { "name": "query", "in": "query", "description": "Only return certificates whose names, subject, issuer, CA, manager, lineage or plugin contain this text.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "shop.example.com" }, { "name": "issue", "in": "query", "description": "Only return certificates failing this check.", "schema": { "type": [ "string", "null" ], "enum": [ "expiring_unmanaged", "renewal_missing", "staging_ca", "self_signed_public", "incomplete_chain", "weak_key", "names_not_covered", "duplicate", null ] } }, { "name": "has_issues", "in": "query", "description": "Only return certificates failing at least one check.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "severity", "in": "query", "description": "Only return certificates whose most severe issue has this severity or worse.", "schema": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", null ] } }, { "name": "expiring_days", "in": "query", "description": "Only return certificates that expire within this many days, including certificates that already expired. 0 returns expired certificates only.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 3650 }, "example": 21 }, { "name": "manager", "in": "query", "description": "Only return certificates issued and renewed by this tool.", "schema": { "type": [ "string", "null" ], "enum": [ "certbot", "acme.sh", "plesk", "directadmin", "forge", null ] } }, { "name": "unmanaged", "in": "query", "description": "Only return certificates without renewal automation: none was found, or the agent could not tell.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "ca", "in": "query", "description": "Only return certificates of this CA: letsencrypt, letsencrypt-staging, zerossl, buypass, google or sectigo. New values may be added.", "schema": { "type": [ "string", "null" ], "maxLength": 32 }, "example": "letsencrypt" }, { "name": "plugin", "in": "query", "description": "Only return certificates issued with this certbot or acme.sh plugin.", "schema": { "type": [ "string", "null" ], "maxLength": 64 }, "example": "dns-domainchief" }, { "name": "sort", "in": "query", "description": "urgency lists the most severe issues first and then the soonest expiry, expiry the soonest expiry first, name sorts by the primary name.", "schema": { "type": [ "string", "null" ], "enum": [ "urgency", "expiry", "name", null ], "default": "urgency" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `ServerCertificate`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ServerCertificate" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/applications": { "get": { "operationId": "applications.index", "description": "Find applications across the servers the authenticated team can see, including servers shared with it: which have a malicious package or open vulnerabilities, and which run a WordPress, Laravel or Symfony release past its end of life. Applications with a malicious package come first, then the most severe vulnerabilities. Every result includes its server.", "summary": "Search applications", "tags": [ "Applications" ], "parameters": [ { "name": "query", "in": "query", "description": "Only return applications whose path or site names contain this text.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "shop.example.com" }, { "name": "kind", "in": "query", "description": "Only return applications of this kind.", "schema": { "type": [ "string", "null" ], "enum": [ "wordpress", "laravel", "symfony", "composer", "node", null ] } }, { "name": "vulnerable", "in": "query", "description": "Only return applications with an open vulnerability in a package they need in production.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "malicious", "in": "query", "description": "Only return applications with an open malicious package.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "end_of_life", "in": "query", "description": "Only return applications whose WordPress, Laravel or Symfony release is past its end of life.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "outdated", "in": "query", "description": "Only return WordPress applications older than WordPress's latest release.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "package", "in": "query", "description": "Only return applications with this Composer or npm package, or WordPress plugin or theme slug, by its exact name, development dependencies included.", "schema": { "type": [ "string", "null" ], "maxLength": 214 }, "example": "guzzlehttp\/guzzle" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `Application`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/Application" }, { "type": "object", "required": [ "server" ] } ] } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/vulnerabilities": { "get": { "operationId": "vulnerabilities.index", "description": "Find vulnerabilities across the servers the authenticated team can see, including servers shared with it: which servers a CVE or advisory affects, which have critical vulnerabilities, or which can be fixed by installing pending updates. Every result includes its server, one entry per server, CVE (or advisory without a CVE) and source package.", "summary": "Search vulnerabilities", "tags": [ "Vulnerabilities" ], "parameters": [ { "name": "cve", "in": "query", "description": "Only return vulnerabilities covered by this CVE or advisory: a CVE ID, or an advisory ID or alias such as DSA-5532-1, USN-6500-1, ALSA-2024:1234 or DEBIAN-CVE-2023-5363.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z][A-Za-z0-9]*([-:][A-Za-z0-9]+)+$", "maxLength": 64 }, "example": "CVE-2023-5363" }, { "name": "severity", "in": "query", "description": "Only return vulnerabilities of this severity or worse. Unknown only matches unrated vulnerabilities.", "schema": { "type": [ "string", "null" ], "enum": [ "critical", "high", "medium", "low", "negligible", "unknown", null ] } }, { "name": "fix_status", "in": "query", "description": "Only return vulnerabilities with this fix status.", "schema": { "type": [ "string", "null" ], "enum": [ "available", "reboot", "released", "none", null ] } }, { "name": "known_exploited", "in": "query", "description": "Only return vulnerabilities CISA lists as known exploited (true), or those it does not list (false).", "schema": { "type": [ "boolean", "null" ] } }, { "name": "public_exploit", "in": "query", "description": "Only return vulnerabilities Metasploit, Nuclei or Exploit-DB has a public exploit of (true), or those without one (false).", "schema": { "type": [ "boolean", "null" ] } }, { "name": "min_epss", "in": "query", "description": "Only return vulnerabilities with at least this EPSS score, the probability of exploitation activity in the next 30 days.", "schema": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "example": 0.1 }, { "name": "package", "in": "query", "description": "Only return vulnerabilities of this source package, or of the source of this binary package.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "openssl" }, { "name": "status", "in": "query", "description": "open for current vulnerabilities, resolved for vulnerabilities that were fixed or no longer apply, all for both.", "schema": { "type": [ "string", "null" ], "enum": [ "open", "resolved", "all", null ], "default": "open" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "advisory", "in": "query", "description": "Only return vulnerabilities covered by this advisory, by ID or alias. Combines with cve.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z][A-Za-z0-9]*([-:][A-Za-z0-9]+)+$", "maxLength": 64 }, "example": "DSA-5532-1" } ], "responses": { "200": { "description": "Array of `ServerVulnerability`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ServerVulnerability" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}\/metrics": { "get": { "operationId": "metrics.latest", "description": "Get the newest value of every metric the server sent in the last 10 minutes. File system metrics are per mount point; disk and network metrics per disk and interface, plus the host total without an instance.", "summary": "Get a server's current metrics", "tags": [ "Metrics" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ServerMetrics`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ServerMetrics" } }, "required": [ "data" ] } } } }, "503": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Metrics are unavailable right now." ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/alert-rules": { "get": { "operationId": "alertRules.index", "description": "List the team's metric alert rules, oldest first. Rules watch the servers the team owns, not servers shared with it.", "summary": "List alert rules", "tags": [ "Alerts" ], "parameters": [ { "name": "query", "in": "query", "description": "Search results by name.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "edge protection" }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `AlertRule`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AlertRule" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:alerts:read" ] }, { "ctp": [ "serverchief:alerts:read" ] }, { "ctt": [ "serverchief:alerts:read" ] } ] }, "post": { "operationId": "alertRules.create", "description": "Create a metric alert rule: when the metric stays above or below the threshold for the whole duration on a server the rule watches, an alert fires and the team members who want metric alerts are notified. Rules are checked every minute.", "summary": "Create an alert rule", "tags": [ "Alerts" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveAlertRuleRequest" } } } }, "responses": { "201": { "description": "The alert rule was created.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AlertRule" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:alerts:write" ] }, { "ctp": [ "serverchief:alerts:write" ] }, { "ctt": [ "serverchief:alerts:write" ] } ] } }, "\/tags": { "get": { "operationId": "tags.index", "description": "List the tags the authenticated team can see: its own tags (access owner) and tags other teams shared with it (access viewer), sorted by name.", "summary": "List tags", "tags": [ "Tags" ], "parameters": [ { "name": "query", "in": "query", "description": "Search results by name.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "edge protection" }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `Tag`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Tag" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:tags:read" ] }, { "ctp": [ "serverchief:tags:read" ] }, { "ctt": [ "serverchief:tags:read" ] } ] }, "post": { "operationId": "tags.create", "description": "Create a tag in the authenticated team. Attach it to servers with the server tags endpoints, and share it to give other teams read-only access to those servers.", "summary": "Create a tag", "tags": [ "Tags" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveTagRequest" } } } }, "responses": { "201": { "description": "The tag was created.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Tag" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:tags:write" ] }, { "ctp": [ "serverchief:tags:write" ] }, { "ctt": [ "serverchief:tags:write" ] } ] } }, "\/agent\/releases": { "get": { "operationId": "agentReleases.index", "description": "List the stable agent releases, newest first, optionally those whose version starts with query. A release is rolled out automatically once its rollout_starts_at has passed.", "summary": "List agent releases", "tags": [ "Agent releases" ], "parameters": [ { "name": "query", "in": "query", "description": "Search results by name.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "edge protection" }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `AgentRelease`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AgentRelease" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/webhooks\/endpoints": { "get": { "operationId": "webhooks.endpoints.index", "description": "List the team's webhook endpoints, oldest first. Signing secrets are not included.", "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "parameters": [ { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `WebhookEndpoint`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookEndpoint" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:webhooks:read" ] }, { "ctp": [ "serverchief:webhooks:read" ] }, { "ctt": [ "serverchief:webhooks:read" ] } ] }, "post": { "operationId": "webhooks.endpoints.create", "description": "Add an endpoint that receives the chosen events. The response is the only time its signing secret is returned until it is rotated. Fails with 422 when the team's plan has no room for another endpoint.", "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateWebhookEndpointRequest" } } } }, "responses": { "201": { "description": "`WebhookEndpoint`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookEndpoint" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:write" ] }, { "ctp": [ "serverchief:webhooks:write" ] }, { "ctt": [ "serverchief:webhooks:write" ] } ] } }, "\/alert-rules\/{rule}": { "get": { "operationId": "alertRules.single", "description": "Get one of the team's metric alert rules.", "summary": "Get an alert rule", "tags": [ "Alerts" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`AlertRule`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AlertRule" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:alerts:read" ] }, { "ctp": [ "serverchief:alerts:read" ] }, { "ctt": [ "serverchief:alerts:read" ] } ] }, "patch": { "operationId": "alertRules.update", "description": "Change an alert rule, or turn it off or on with `enabled`. Fields left out keep their value. A change closes the rule's firing alerts, which no longer say what the rule says; they fire again at the next check if the new rule is breached.", "summary": "Update an alert rule", "tags": [ "Alerts" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveAlertRuleRequest" } } } }, "responses": { "200": { "description": "`AlertRule`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AlertRule" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:alerts:write" ] }, { "ctp": [ "serverchief:alerts:write" ] }, { "ctt": [ "serverchief:alerts:write" ] } ] }, "delete": { "operationId": "alertRules.delete", "description": "Delete an alert rule and close its firing alerts. Its past alerts stay in the alert history with what the rule said.", "summary": "Delete an alert rule", "tags": [ "Alerts" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The alert rule was deleted.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:alerts:write" ] }, { "ctp": [ "serverchief:alerts:write" ] }, { "ctt": [ "serverchief:alerts:write" ] } ] } }, "\/alerts": { "get": { "operationId": "alerts.index", "description": "List the alerts the team's rules raised, firing alerts first, then the newest first. Alerts stay after their rule changed or was deleted, and go when their server is deleted.", "summary": "List alerts", "tags": [ "Alerts" ], "parameters": [ { "name": "status", "in": "query", "description": "Only return firing or resolved alerts, both when omitted.", "schema": { "type": [ "string", "null" ], "enum": [ "firing", "resolved", null ] } }, { "name": "server", "in": "query", "description": "Only return alerts of this server.", "schema": { "type": [ "string", "null" ], "maxLength": 64 }, "example": "server_01j8q8zk2f4m6n7p9r1s3t5v7x" }, { "name": "rule", "in": "query", "description": "Only return alerts of this rule, including those it raised before it changed.", "schema": { "type": [ "string", "null" ], "maxLength": 64 }, "example": "rule_01j8q8zk2f4m6n7p9r1s3t5v7x" }, { "name": "metric", "in": "query", "description": "Only return alerts of this metric.", "schema": { "type": [ "string", "null" ], "enum": [ "cpu_used", "cpu_iowait", "cpu_steal", "load_per_core", "memory_used", "swap_used", "disk_space_used", "inodes_used", "disk_busy", "disk_read", "disk_write", "disk_operations", "network_in", "network_out", "packets_in", "packets_out", "network_errors", "tcp_connections", "tcp_time_wait", "processes_blocked", "threads", "uptime", null ] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `Alert`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Alert" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:alerts:read" ] }, { "ctp": [ "serverchief:alerts:read" ] }, { "ctt": [ "serverchief:alerts:read" ] } ] } }, "\/alerts\/{alert}": { "get": { "operationId": "alerts.single", "description": "Get one of the alerts the team's rules raised.", "summary": "Get an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "alert", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Alert`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Alert" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:alerts:read" ] }, { "ctp": [ "serverchief:alerts:read" ] }, { "ctt": [ "serverchief:alerts:read" ] } ] } }, "\/applications\/{application}": { "get": { "operationId": "applications.single", "description": "Show an application of a server the authenticated team can see: its kind and version, sites, lockfiles and how many packages, plugins, themes and open vulnerabilities it has.", "summary": "Show an application", "tags": [ "Applications" ], "parameters": [ { "name": "application", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Application`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/Application" }, { "type": "object", "required": [ "server" ] } ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/applications\/{application}\/packages": { "get": { "operationId": "applications.packages", "description": "List the Composer and npm packages of an application's lockfiles and the plugins and themes of a WordPress install, read from their headers, with the latest stable release on Packagist, npm or WordPress.org. Packages only development dependencies need are left out unless asked for. Whether a WordPress plugin is active is not known.", "summary": "List an application's packages", "tags": [ "Applications" ], "parameters": [ { "name": "application", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Only return packages, plugins and themes whose name contains this text.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "guzzle" }, { "name": "ecosystem", "in": "query", "description": "Only return packages of this ecosystem, or WordPress plugins or themes.", "schema": { "type": [ "string", "null" ], "enum": [ "composer", "npm", "wordpress-plugin", "wordpress-theme", "wordpress-core", null ] } }, { "name": "include_dev", "in": "query", "description": "Also return packages only development dependencies need.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "outdated", "in": "query", "description": "Only return packages, plugins and themes older than their latest stable release.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `ApplicationPackage`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ApplicationPackage" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/applications\/{application}\/vulnerabilities": { "get": { "operationId": "applications.vulnerabilities", "description": "List the open vulnerabilities of an application's Composer and npm packages, matched against GitHub, Drupal and malicious package advisories: malicious packages first, then the most severe, known exploited, with a public exploit and most likely exploited. Packages only development dependencies need and resolved vulnerabilities are left out unless asked for.", "summary": "List an application's vulnerabilities", "tags": [ "Applications" ], "parameters": [ { "name": "application", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "description": "Only return vulnerabilities of this severity or worse. Malicious packages are critical.", "schema": { "type": [ "string", "null" ], "enum": [ "critical", "high", "medium", "low", "negligible", "unknown", null ] } }, { "name": "include_dev", "in": "query", "description": "Also return vulnerabilities of packages only development dependencies need.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "include_resolved", "in": "query", "description": "Also return resolved vulnerabilities.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `ApplicationVulnerability`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ApplicationVulnerability" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/certificates\/{certificate}": { "get": { "operationId": "certificates.single", "description": "Show a certificate of a server the authenticated team can see: its names, validity, key, chain, the sites and services using it, the tool renewing it and the checks it fails.", "summary": "Show a certificate", "tags": [ "Certificates" ], "parameters": [ { "name": "certificate", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ServerCertificate`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/ServerCertificate" }, { "type": "object", "required": [ "server" ] } ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}\/metrics\/series": { "get": { "operationId": "metrics.series", "description": "Get the average, lowest and highest value per bucket of up to 10 metrics over a range ending now, such as for charts or to see how a value developed. Samples are kept per minute for 8 days, per 5 minutes for 90 days and per hour for 2 years, as far back as the metrics history of the team's plan.", "summary": "Get a server's metric series", "tags": [ "Metrics" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "description": "The period to return, ending now. Points are averages per bucket: 1 minute up to 6h, 5 minutes for 24h, 30 minutes for 7d, 2 hours for 30d and a day for 1y.", "schema": { "type": [ "string", "null" ], "enum": [ "1h", "6h", "24h", "7d", "30d", "1y", null ], "default": "6h" } }, { "name": "metrics[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "cpu.user", "cpu.system", "cpu.iowait", "cpu.steal", "cpu.idle", "cpu.cores", "load.1", "load.5", "load.15", "memory.total", "memory.available", "memory.used", "memory.cached", "memory.used_pct", "swap.total", "swap.used", "swap.used_pct", "fs.size", "fs.used", "fs.used_pct", "fs.inodes_used_pct", "disk.read_bps", "disk.write_bps", "disk.read_iops", "disk.write_iops", "disk.util_pct", "net.rx_bps", "net.tx_bps", "net.rx_pps", "net.tx_pps", "net.errors", "net.drops", "tcp.established", "tcp.time_wait", "procs.running", "procs.blocked", "procs.total", "system.uptime" ] }, "minItems": 1, "maxItems": 10 } }, { "name": "instance", "in": "query", "description": "Only return this mount point, disk or interface. Without it, every instance is returned; host totals of disks and interfaces have an empty instance.", "schema": { "type": [ "string", "null" ], "maxLength": 128 }, "example": "eth0" } ], "responses": { "200": { "description": "`ServerMetricSeries`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ServerMetricSeries" } }, "required": [ "data" ] } } } }, "503": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Metrics are unavailable right now." ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}": { "get": { "operationId": "servers.single", "description": "Show one server the authenticated team can see, including servers shared with it (access viewer).", "summary": "Show a server", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Server`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Server" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] }, "patch": { "operationId": "servers.update", "description": "Update a server belonging to the authenticated team. Omitted fields retain their current values, and null clears the hostname. Metadata is merged into the existing metadata and tags replace the server's tags. Changing package_metadata_refresh is sent to the agent with its configuration. Servers shared with the team cannot be changed.", "summary": "Update a server", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveServerRequest" } } } }, "responses": { "200": { "description": "`Server`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Server" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:write" ] }, { "ctp": [ "serverchief:servers:write" ] }, { "ctt": [ "serverchief:servers:write" ] } ] }, "delete": { "operationId": "servers.delete", "description": "Remove a server from the authenticated team's inventory. The agent credential is revoked, so the agent stops reporting.", "summary": "Delete a server", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The server was deleted.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:write" ] }, { "ctp": [ "serverchief:servers:write" ] }, { "ctt": [ "serverchief:servers:write" ] } ] } }, "\/servers\/{server}\/enrollment-token": { "post": { "operationId": "servers.enrollment-token", "description": "Issue a new one-time enrollment token and install command, which invalidates any earlier unused token of the server. For a pending server the token enrolls its first agent. For an enrolled server it reinstalls the agent: the current agent keeps reporting until the new one enrolls, then its credential is revoked.", "summary": "Issue an enrollment token", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "The token was issued.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ServerEnrollment" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:write" ] }, { "ctp": [ "serverchief:servers:write" ] }, { "ctt": [ "serverchief:servers:write" ] } ] } }, "\/servers\/{server}\/refresh": { "post": { "operationId": "servers.refresh", "description": "Queue a refresh_inventory command: the agent collects the datasets now and reports whatever changed. It is woken up right away when realtime is available and otherwise picks the command up on its next heartbeat. An identical command that the agent has not fetched yet is returned instead of queueing another one.", "summary": "Refresh a server's inventory", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/RefreshServerRequest" } } } }, "responses": { "202": { "description": "The command was queued.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ServerCommand" } }, "required": [ "data" ] } } } }, "409": { "description": "The server has no enrolled agent yet.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "The server has no enrolled agent yet." ] } }, "required": [ "message" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:write" ] }, { "ctp": [ "serverchief:servers:write" ] }, { "ctt": [ "serverchief:servers:write" ] } ] } }, "\/servers\/{server}\/agent-update": { "post": { "operationId": "servers.updateAgent", "description": "Queue an update_agent command that installs the newest agent release from the Server Chief package repository, rolling back when the new version does not start. It skips the soak time and batching of the automatic rollout, but the server must be online, report that it can update itself, run a stable agent version older than the newest release and have no agent update in progress. An update to the same version that is already in progress is returned instead.", "summary": "Update a server's agent", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "The command was queued.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ServerCommand" } }, "required": [ "data" ] } } } }, "409": { "description": "The agent cannot be updated now, the message says why.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:write" ] }, { "ctp": [ "serverchief:servers:write" ] }, { "ctt": [ "serverchief:servers:write" ] } ] } }, "\/servers\/{server}\/reboot": { "post": { "operationId": "servers.reboot", "description": "Queue a reboot command. The agent waits up to 15 minutes for a running package manager, warns logged-in users and reboots the server one minute later, then reports the result once it started again. The server's boot_time moves once it rebooted. The server must be online and its agent must report agent.reboot.available, which needs agent 0.4.0 or later and is false when the server's operator turned reboots off on the server. Only the team that owns the server can reboot it. A reboot that is already queued or running is returned instead.", "summary": "Reboot a server", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "The command was queued.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ServerCommand" } }, "required": [ "data" ] } } } }, "409": { "description": "The server cannot be rebooted now, the message says why.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:control" ] }, { "ctp": [ "serverchief:servers:control" ] }, { "ctt": [ "serverchief:servers:control" ] } ] } }, "\/servers\/{server}\/package-upgrades": { "post": { "operationId": "servers.upgradePackages", "description": "Queue an upgrade_packages command. The agent waits up to an hour for a running package manager, updates itself first when a newer agent release exists (regardless of the automatic agent update settings), then installs the pending security updates or every pending update, keeping local configuration files. With restart_services the services that use updated libraries are restarted, with reboot_if_required Server Chief reboots the server afterwards when the agent reports that a reboot is required. The result, with the full output of the package manager, arrives when the agent is done. The server must be online and its agent must report agent.upgrade_packages.available, which needs agent 0.4.0 or later and is false when the server's operator turned it off on the server. Only the team that owns the server can install updates. An update run that is already queued or running is returned instead.", "summary": "Install a server's package updates", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpgradeServerPackagesRequest" } } } }, "responses": { "202": { "description": "The command was queued.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ServerCommand" } }, "required": [ "data" ] } } } }, "409": { "description": "The updates cannot be installed now, the message says why.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:control" ] }, { "ctp": [ "serverchief:servers:control" ] }, { "ctt": [ "serverchief:servers:control" ] } ] } }, "\/servers\/{server}\/packages": { "get": { "operationId": "servers.packages", "description": "List the packages installed on a server, sorted by name, with the version a pending update would install.", "summary": "List a server's packages", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter by package name, a substring match unless it contains * as a wildcard.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "openssl" }, { "name": "updates", "in": "query", "description": "Only return packages with a pending update.", "schema": { "type": "boolean" } }, { "name": "origin", "in": "query", "description": "Only return packages from an origin: a repository vendor or alias such as sury, esm or ppa:ondrej\/php, third-party for packages only third-party repositories offer, or none for packages no configured repository offers.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9][a-z0-9._:\\\/+-]*$", "maxLength": 191 }, "example": "third-party" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `ServerPackage`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ServerPackage" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}\/software": { "get": { "operationId": "servers.software", "description": "List the software products detected from a server's packages, one entry per product and major.minor, with end-of-life data from endoflife.date.", "summary": "List a server's software", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `ServerSoftware`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ServerSoftware" } } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}\/vhosts": { "get": { "operationId": "servers.vhosts", "description": "List the virtual hosts the agent found in the server's web server and panel configuration, sorted by name, with their PHP version and TLS certificate.", "summary": "List a server's sites", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "description": "Only return sites serving this domain, by name or alias. A host also matches wildcard aliases covering it, and *.example.com matches every subdomain.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "shop.example.com" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `ServerVhost`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ServerVhost" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}\/certificates": { "get": { "operationId": "servers.certificates", "description": "List the certificates of the server's sites, mail services and panel, each once however many use it, the most severe issues first, with the tool renewing them and the checks they fail.", "summary": "List a server's certificates", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Only return certificates whose names, subject, issuer, CA, manager, lineage or plugin contain this text.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "shop.example.com" }, { "name": "issue", "in": "query", "description": "Only return certificates failing this check.", "schema": { "type": [ "string", "null" ], "enum": [ "expiring_unmanaged", "renewal_missing", "staging_ca", "self_signed_public", "incomplete_chain", "weak_key", "names_not_covered", "duplicate", null ] } }, { "name": "has_issues", "in": "query", "description": "Only return certificates failing at least one check.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "severity", "in": "query", "description": "Only return certificates whose most severe issue has this severity or worse.", "schema": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", null ] } }, { "name": "expiring_days", "in": "query", "description": "Only return certificates that expire within this many days, including certificates that already expired. 0 returns expired certificates only.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 3650 }, "example": 21 }, { "name": "manager", "in": "query", "description": "Only return certificates issued and renewed by this tool.", "schema": { "type": [ "string", "null" ], "enum": [ "certbot", "acme.sh", "plesk", "directadmin", "forge", null ] } }, { "name": "unmanaged", "in": "query", "description": "Only return certificates without renewal automation: none was found, or the agent could not tell.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "ca", "in": "query", "description": "Only return certificates of this CA: letsencrypt, letsencrypt-staging, zerossl, buypass, google or sectigo. New values may be added.", "schema": { "type": [ "string", "null" ], "maxLength": 32 }, "example": "letsencrypt" }, { "name": "plugin", "in": "query", "description": "Only return certificates issued with this certbot or acme.sh plugin.", "schema": { "type": [ "string", "null" ], "maxLength": 64 }, "example": "dns-domainchief" }, { "name": "sort", "in": "query", "description": "urgency lists the most severe issues first and then the soonest expiry, expiry the soonest expiry first, name sorts by the primary name.", "schema": { "type": [ "string", "null" ], "enum": [ "urgency", "expiry", "name", null ], "default": "urgency" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `ServerCertificate`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ServerCertificate" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}\/applications": { "get": { "operationId": "servers.applications", "description": "List the WordPress, Laravel, Symfony and other Composer or npm applications the server's sites serve, those with a malicious package first, then the most severe open vulnerabilities.", "summary": "List a server's applications", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Only return applications whose path or site names contain this text.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "shop.example.com" }, { "name": "kind", "in": "query", "description": "Only return applications of this kind.", "schema": { "type": [ "string", "null" ], "enum": [ "wordpress", "laravel", "symfony", "composer", "node", null ] } }, { "name": "vulnerable", "in": "query", "description": "Only return applications with an open vulnerability in a package they need in production.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "malicious", "in": "query", "description": "Only return applications with an open malicious package.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "end_of_life", "in": "query", "description": "Only return applications whose WordPress, Laravel or Symfony release is past its end of life.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "outdated", "in": "query", "description": "Only return WordPress applications older than WordPress's latest release.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "package", "in": "query", "description": "Only return applications with this Composer or npm package, or WordPress plugin or theme slug, by its exact name, development dependencies included.", "schema": { "type": [ "string", "null" ], "maxLength": 214 }, "example": "guzzlehttp\/guzzle" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `Application`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Application" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}\/repositories": { "get": { "operationId": "servers.repositories", "description": "List the apt, yum and dnf repositories configured on a server, enabled ones with issues first, with the vendor classified from their URIs, how they are signed and how many installed packages they offer.", "summary": "List a server's package repositories", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `ServerRepository`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ServerRepository" } } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}\/vulnerabilities": { "get": { "operationId": "servers.vulnerabilities", "description": "List the vulnerabilities security advisories report for the server's installed packages, the most severe first (known exploited, then with a public exploit, then higher EPSS scores first within a severity): one entry per CVE (or advisory without a CVE) and source package, with the installed and fixed version and whether the package manager offers the fix. Resolved vulnerabilities are kept for history. A server whose release has no advisory data returns no vulnerabilities, see `vulnerabilities` of the server.", "summary": "List a server's vulnerabilities", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cve", "in": "query", "description": "Only return vulnerabilities covered by this CVE or advisory: a CVE ID, or an advisory ID or alias such as DSA-5532-1, USN-6500-1, ALSA-2024:1234 or DEBIAN-CVE-2023-5363.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z][A-Za-z0-9]*([-:][A-Za-z0-9]+)+$", "maxLength": 64 }, "example": "CVE-2023-5363" }, { "name": "severity", "in": "query", "description": "Only return vulnerabilities of this severity or worse. Unknown only matches unrated vulnerabilities.", "schema": { "type": [ "string", "null" ], "enum": [ "critical", "high", "medium", "low", "negligible", "unknown", null ] } }, { "name": "fix_status", "in": "query", "description": "Only return vulnerabilities with this fix status.", "schema": { "type": [ "string", "null" ], "enum": [ "available", "reboot", "released", "none", null ] } }, { "name": "known_exploited", "in": "query", "description": "Only return vulnerabilities CISA lists as known exploited (true), or those it does not list (false).", "schema": { "type": [ "boolean", "null" ] } }, { "name": "public_exploit", "in": "query", "description": "Only return vulnerabilities Metasploit, Nuclei or Exploit-DB has a public exploit of (true), or those without one (false).", "schema": { "type": [ "boolean", "null" ] } }, { "name": "min_epss", "in": "query", "description": "Only return vulnerabilities with at least this EPSS score, the probability of exploitation activity in the next 30 days.", "schema": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "example": 0.1 }, { "name": "package", "in": "query", "description": "Only return vulnerabilities of this source package, or of the source of this binary package.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "openssl" }, { "name": "status", "in": "query", "description": "open for current vulnerabilities, resolved for vulnerabilities that were fixed or no longer apply, all for both.", "schema": { "type": [ "string", "null" ], "enum": [ "open", "resolved", "all", null ], "default": "open" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Array of `ServerVulnerability`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ServerVulnerability" } } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}\/changes": { "get": { "operationId": "servers.changes", "description": "List the server's change history as far back as the change history of the team's plan, newest first: what changed between inventory reports (packages installed, upgraded or removed, addresses, sites, certificates, repositories, the operating system and hardware), vulnerabilities found and resolved, and agent updates.", "summary": "List a server's changes", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "query", "description": "Only return changes of a dataset.", "schema": { "type": [ "string", "null" ], "enum": [ "system", "hardware", "network", "resolvers", "cloud", "packages", "vhosts", "certificates", "repositories", "applications", "vulnerabilities", "agent", null ] }, "example": "packages" }, { "name": "kind", "in": "query", "description": "Only return changes of a kind.", "schema": { "type": [ "string", "null" ], "enum": [ "changed", "added", "removed", null ] } }, { "name": "since", "in": "query", "description": "Only return changes detected at or after this ISO 8601 date or timestamp.", "schema": { "type": [ "string", "null" ], "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `ServerChange`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ServerChange" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}\/inventory\/{dataset}": { "get": { "operationId": "servers.inventory", "description": "Show one inventory dataset as the server's agent last reported it: `system`, `hardware`, `storage`, `network`, `resolvers`, `cloud` or `updates`. The payload is null until the agent reports the dataset, and when the team or server turned off collecting it (`collected` is false).", "summary": "Show a server's inventory dataset", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ServerInventory`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ServerInventory" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/servers\/{server}\/tags": { "put": { "operationId": "servers.tags.replace", "description": "Set the complete list of tags of one of the team's servers. Only the team's own tags can be attached, and servers shared with the team cannot be changed.", "summary": "Replace a server's tags", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ReplaceServerTagsRequest" } } } }, "responses": { "200": { "description": "`Server`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Server" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:write" ] }, { "ctp": [ "serverchief:servers:write" ] }, { "ctt": [ "serverchief:servers:write" ] } ] }, "patch": { "operationId": "servers.tags.update", "description": "Attach and detach tags of one of the team's servers, other tags are kept. Detaching runs after attaching. Only the team's own tags can be attached, and servers shared with the team cannot be changed.", "summary": "Attach or detach server tags", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateServerTagsRequest" } } } }, "responses": { "200": { "description": "`Server`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Server" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:write" ] }, { "ctp": [ "serverchief:servers:write" ] }, { "ctt": [ "serverchief:servers:write" ] } ] } }, "\/install-commands": { "get": { "operationId": "installCommands.index", "description": "List the team's install commands that can still add servers, the newest first. Their tokens are never shown again.", "summary": "List install commands", "tags": [ "Servers" ], "parameters": [ { "name": "query", "in": "query", "description": "Search results by name.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "edge protection" }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Array of `InstallCommand`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/InstallCommand" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] }, "post": { "operationId": "installCommands.create", "description": "Create a command that installs the agent and adds the server to the team when the agent enrolls, named after its hostname. A single-use command adds one server, otherwise it adds any number of servers until it expires. The token and command are only returned in this response.", "summary": "Create an install command", "tags": [ "Servers" ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateInstallCommandRequest" } } } }, "responses": { "201": { "description": "The install command was created.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/InstallCommand" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:servers:write" ] }, { "ctp": [ "serverchief:servers:write" ] }, { "ctt": [ "serverchief:servers:write" ] } ] } }, "\/install-commands\/{installCommand}\/revoke": { "post": { "operationId": "installCommands.revoke", "description": "Stop an install command from adding servers. Servers it already added keep working.", "summary": "Revoke an install command", "tags": [ "Servers" ], "parameters": [ { "name": "installCommand", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`InstallCommand`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/InstallCommand" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:write" ] }, { "ctp": [ "serverchief:servers:write" ] }, { "ctt": [ "serverchief:servers:write" ] } ] } }, "\/tags\/{tag}": { "get": { "operationId": "tags.single", "description": "Show one of the team's tags, or a tag shared with the team.", "summary": "Show a tag", "tags": [ "Tags" ], "parameters": [ { "name": "tag", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Tag`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Tag" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:tags:read" ] }, { "ctp": [ "serverchief:tags:read" ] }, { "ctt": [ "serverchief:tags:read" ] } ] }, "patch": { "operationId": "tags.update", "description": "Rename or recolour one of the team's tags. Tags shared with the team cannot be changed.", "summary": "Update a tag", "tags": [ "Tags" ], "parameters": [ { "name": "tag", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveTagRequest" } } } }, "responses": { "200": { "description": "`Tag`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Tag" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:tags:write" ] }, { "ctp": [ "serverchief:tags:write" ] }, { "ctt": [ "serverchief:tags:write" ] } ] }, "delete": { "operationId": "tags.delete", "description": "Delete one of the team's tags. It is removed from every server, and teams it was shared with lose access to the servers they only saw through it.", "summary": "Delete a tag", "tags": [ "Tags" ], "parameters": [ { "name": "tag", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The tag was deleted.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:tags:write" ] }, { "ctp": [ "serverchief:tags:write" ] }, { "ctt": [ "serverchief:tags:write" ] } ] } }, "\/tags\/{tag}\/shares": { "get": { "operationId": "tags.shares.index", "description": "List the teams one of the team's tags is shared with. Only the owner team can see the shares of a tag.", "summary": "List a tag's shares", "tags": [ "Tags" ], "parameters": [ { "name": "tag", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `TagShare`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TagShare" } } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:tags:read" ] }, { "ctp": [ "serverchief:tags:read" ] }, { "ctt": [ "serverchief:tags:read" ] } ] }, "post": { "operationId": "tags.shares.create", "description": "Share one of the team's tags with another team by its slug. The other team then sees every server of this team that carries the tag, read-only, until the tag is detached, unshared or deleted. Sharing again with the same team updates the role. Shared servers never count towards the other team's plan.", "summary": "Share a tag", "tags": [ "Tags" ], "parameters": [ { "name": "tag", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ShareTagRequest" } } } }, "responses": { "201": { "description": "The tag is shared with the team.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TagShare" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:tags:write" ] }, { "ctp": [ "serverchief:tags:write" ] }, { "ctt": [ "serverchief:tags:write" ] } ] } }, "\/tags\/{tag}\/shares\/{team}": { "delete": { "operationId": "tags.shares.delete", "description": "Stop sharing one of the team's tags with a team. The team immediately loses access to the servers it only saw through the tag.\nA team a tag is shared with can leave the share by passing its own slug.", "summary": "Unshare a tag", "tags": [ "Tags" ], "parameters": [ { "name": "tag", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "team", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The tag is no longer shared with the team.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:tags:write" ] }, { "ctp": [ "serverchief:tags:write" ] }, { "ctt": [ "serverchief:tags:write" ] } ] } }, "\/advisories\/{advisory}": { "get": { "operationId": "advisories.single", "description": "Show a security advisory by its OSV ID, such as DSA-5532-1, DEBIAN-CVE-2023-5363, USN-6450-1, UBUNTU-CVE-2023-5363, ALSA-2024:0025 or RLSA-2024:0003, with the fixed versions per release. Only advisories for the releases Server Chief imports are available. Find the servers a CVE affects with the vulnerabilities search instead.", "summary": "Show an advisory", "tags": [ "Vulnerabilities" ], "parameters": [ { "name": "advisory", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Advisory`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Advisory" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:servers:read" ] }, { "ctp": [ "serverchief:servers:read" ] }, { "ctt": [ "serverchief:servers:read" ] } ] } }, "\/webhooks\/event-types": { "get": { "operationId": "webhooks.eventTypes.index", "description": "List the event types endpoints can subscribe to, with the heading they are grouped under and when they are sent.", "summary": "List webhook event types", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Array of `WebhookEventTypeDetails`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookEventTypeDetails" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:read" ] }, { "ctp": [ "serverchief:webhooks:read" ] }, { "ctt": [ "serverchief:webhooks:read" ] } ] } }, "\/webhooks\/endpoints\/{endpoint}": { "get": { "operationId": "webhooks.endpoints.single", "description": "Get an endpoint of the team. Its signing secret is not included.", "summary": "Get a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebhookEndpoint`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookEndpoint" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:read" ] }, { "ctp": [ "serverchief:webhooks:read" ] }, { "ctt": [ "serverchief:webhooks:read" ] } ] }, "patch": { "operationId": "webhooks.endpoints.update", "description": "Change an endpoint's URL, description or events. Fields left out keep their value.", "summary": "Update a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "`WebhookEndpoint`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookEndpoint" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:write" ] }, { "ctp": [ "serverchief:webhooks:write" ] }, { "ctt": [ "serverchief:webhooks:write" ] } ] }, "delete": { "operationId": "webhooks.endpoints.delete", "description": "Delete an endpoint with its delivery log. Deliveries still waiting for an attempt are not sent.", "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:write" ] }, { "ctp": [ "serverchief:webhooks:write" ] }, { "ctt": [ "serverchief:webhooks:write" ] } ] } }, "\/webhooks\/endpoints\/{endpoint}\/enable": { "post": { "operationId": "webhooks.endpoints.enable", "description": "Start sending events to a disabled endpoint again. Events that happened while it was disabled are not sent, resend them from its deliveries or the events.", "summary": "Enable a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebhookEndpoint`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookEndpoint" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:write" ] }, { "ctp": [ "serverchief:webhooks:write" ] }, { "ctt": [ "serverchief:webhooks:write" ] } ] } }, "\/webhooks\/endpoints\/{endpoint}\/disable": { "post": { "operationId": "webhooks.endpoints.disable", "description": "Stop sending events to an endpoint. Its deliveries waiting for a retry are cancelled.", "summary": "Disable a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebhookEndpoint`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookEndpoint" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:write" ] }, { "ctp": [ "serverchief:webhooks:write" ] }, { "ctt": [ "serverchief:webhooks:write" ] } ] } }, "\/webhooks\/endpoints\/{endpoint}\/rotate-secret": { "post": { "operationId": "webhooks.endpoints.rotateSecret", "description": "Replace the signing secret and return the new one. For the next 24 hours deliveries are signed with both, so receivers can switch without rejecting any. Fails with 422 while the secret from the last rotation still signs, unless `replace_previous` is true.", "summary": "Rotate a webhook endpoint's secret", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/RotateWebhookSecretRequest" } } } }, "responses": { "200": { "description": "`WebhookEndpoint`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookEndpoint" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:write" ] }, { "ctp": [ "serverchief:webhooks:write" ] }, { "ctt": [ "serverchief:webhooks:write" ] } ] } }, "\/webhooks\/endpoints\/{endpoint}\/test": { "post": { "operationId": "webhooks.endpoints.sendTest", "description": "Send a `webhook_endpoint.test` event to an enabled endpoint, to check that it receives and verifies deliveries. The delivery is queued, get it later to see how it went.", "summary": "Send a test event", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "`WebhookDelivery`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookDelivery" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:write" ] }, { "ctp": [ "serverchief:webhooks:write" ] }, { "ctt": [ "serverchief:webhooks:write" ] } ] } }, "\/webhooks\/endpoints\/{endpoint}\/deliveries": { "get": { "operationId": "webhooks.deliveries.index", "description": "List the deliveries of events to an endpoint, newest first. Deliveries are kept for 30 days.", "summary": "List an endpoint's deliveries", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "type", "in": "query", "description": "Only events of this type.", "schema": { "type": "string", "enum": [ "server.created", "server.enrolled", "server.updated", "server.deleted", "server.offline", "server.online", "server.reboot_stalled", "alert.fired", "alert.resolved", "metrics.stalled", "metrics.resumed", "server.storage_unhealthy", "server.storage_healthy", "webhook_endpoint.test" ] }, "example": "server.offline" }, { "name": "status", "in": "query", "description": "Only deliveries in this state.", "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed", "cancelled" ] } } ], "responses": { "200": { "description": "Paginated set of `WebhookDelivery`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookDelivery" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:webhooks:read" ] }, { "ctp": [ "serverchief:webhooks:read" ] }, { "ctt": [ "serverchief:webhooks:read" ] } ] } }, "\/webhooks\/deliveries\/{delivery}": { "get": { "operationId": "webhooks.deliveries.single", "description": "Get a delivery with every attempt: the request headers that were sent and the response the endpoint gave.", "summary": "Get a webhook delivery", "tags": [ "Webhooks" ], "parameters": [ { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebhookDelivery`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/WebhookDelivery" }, { "type": "object", "required": [ "attempt_log" ] } ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:read" ] }, { "ctp": [ "serverchief:webhooks:read" ] }, { "ctt": [ "serverchief:webhooks:read" ] } ] } }, "\/webhooks\/deliveries\/{delivery}\/resend": { "post": { "operationId": "webhooks.deliveries.resend", "description": "Send a delivery again, whatever its state, as its next attempt with the same event ID. A resend does not use up automatic retries. The endpoint must be enabled.", "summary": "Resend a webhook delivery", "tags": [ "Webhooks" ], "parameters": [ { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "`WebhookDelivery`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookDelivery" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:write" ] }, { "ctp": [ "serverchief:webhooks:write" ] }, { "ctt": [ "serverchief:webhooks:write" ] } ] } }, "\/webhooks\/events": { "get": { "operationId": "webhooks.events.index", "description": "List the events sent to the team's endpoints, newest first. Events are only kept when an endpoint received them, for 30 days.", "summary": "List webhook events", "tags": [ "Webhooks" ], "parameters": [ { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "type", "in": "query", "description": "Only events of this type.", "schema": { "type": "string", "enum": [ "server.created", "server.enrolled", "server.updated", "server.deleted", "server.offline", "server.online", "server.reboot_stalled", "alert.fired", "alert.resolved", "metrics.stalled", "metrics.resumed", "server.storage_unhealthy", "server.storage_healthy", "webhook_endpoint.test" ] }, "example": "server.offline" } ], "responses": { "200": { "description": "Paginated set of `WebhookEvent`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookEvent" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "serverchief:webhooks:read" ] }, { "ctp": [ "serverchief:webhooks:read" ] }, { "ctt": [ "serverchief:webhooks:read" ] } ] } }, "\/webhooks\/events\/{event}": { "get": { "operationId": "webhooks.events.single", "description": "Get an event with its payload and its delivery to each endpoint.", "summary": "Get a webhook event", "tags": [ "Webhooks" ], "parameters": [ { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebhookEvent`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/WebhookEvent" }, { "type": "object", "required": [ "deliveries" ] } ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:read" ] }, { "ctp": [ "serverchief:webhooks:read" ] }, { "ctt": [ "serverchief:webhooks:read" ] } ] } }, "\/webhooks\/events\/{event}\/resend": { "post": { "operationId": "webhooks.events.resend", "description": "Send an event to one of the team's enabled endpoints, as the next attempt of its delivery there or as a new delivery when it has none. Use it to catch an endpoint up after it was disabled.", "summary": "Resend a webhook event", "tags": [ "Webhooks" ], "parameters": [ { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ResendWebhookEventRequest" } } } }, "responses": { "202": { "description": "`WebhookDelivery`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookDelivery" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "serverchief:webhooks:write" ] }, { "ctp": [ "serverchief:webhooks:write" ] }, { "ctt": [ "serverchief:webhooks:write" ] } ] } } }, "webhooks": { "server.created": { "post": { "operationId": "webhook.server.created", "summary": "A server was added and waits for its agent.", "tags": [ "Servers" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ServerCreatedEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "server.enrolled": { "post": { "operationId": "webhook.server.enrolled", "summary": "A server's agent enrolled for the first time.", "tags": [ "Servers" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ServerEnrolledEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "server.updated": { "post": { "operationId": "webhook.server.updated", "summary": "A server's name, metadata, location or settings changed.", "tags": [ "Servers" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ServerUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "server.deleted": { "post": { "operationId": "webhook.server.deleted", "summary": "A server was removed.", "tags": [ "Servers" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ServerDeletedEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "server.offline": { "post": { "operationId": "webhook.server.offline", "summary": "A server stopped checking in.", "tags": [ "Availability" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ServerOfflineEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "server.online": { "post": { "operationId": "webhook.server.online", "summary": "An offline server checks in again.", "tags": [ "Availability" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ServerOnlineEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "server.reboot_stalled": { "post": { "operationId": "webhook.server.reboot_stalled", "summary": "A server did not come back after a reboot.", "tags": [ "Availability" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ServerRebootStalledEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "alert.fired": { "post": { "operationId": "webhook.alert.fired", "summary": "A metric alert rule fired.", "tags": [ "Metric alerts" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/AlertFiredEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "alert.resolved": { "post": { "operationId": "webhook.alert.resolved", "summary": "A firing alert resolved.", "tags": [ "Metric alerts" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/AlertResolvedEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "metrics.stalled": { "post": { "operationId": "webhook.metrics.stalled", "summary": "An online server stopped delivering metrics.", "tags": [ "Metric alerts" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MetricsStalledEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "metrics.resumed": { "post": { "operationId": "webhook.metrics.resumed", "summary": "A server delivers metrics again.", "tags": [ "Metric alerts" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MetricsResumedEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "server.storage_unhealthy": { "post": { "operationId": "webhook.server.storage_unhealthy", "summary": "A RAID array or ZFS pool degraded, or a disk failed.", "tags": [ "Storage health" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ServerStorageUnhealthyEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "server.storage_healthy": { "post": { "operationId": "webhook.server.storage_healthy", "summary": "A server's storage is healthy again.", "tags": [ "Storage health" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ServerStorageHealthyEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } }, "webhook_endpoint.test": { "post": { "operationId": "webhook.webhook_endpoint.test", "summary": "A test event sent from the dashboard.", "tags": [ "Testing" ], "parameters": [ { "$ref": "#\/components\/parameters\/WebhookId" }, { "$ref": "#\/components\/parameters\/WebhookTimestamp" }, { "$ref": "#\/components\/parameters\/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WebhookEndpointTestEvent" } } } }, "responses": { "2XX": { "description": "Any `2xx` status within 15 seconds acknowledges the delivery. Any other status, a timeout or a redirect fails it, and it is retried." } } } } }, "components": { "securitySchemes": { "ctp": { "type": "http", "description": "Chief Tools personal access token.", "scheme": "bearer", "bearerFormat": "ctp_*" }, "openid": { "type": "openIdConnect", "openIdConnectUrl": "https:\/\/account.chief.app\/.well-known\/openid-configuration" }, "ctt": { "type": "http", "description": "Chief Tools team access token.", "scheme": "bearer", "bearerFormat": "ctt_*" } }, "schemas": { "Advisory": { "type": "object", "properties": { "id": { "type": "string", "description": "OSV ID of the advisory.", "examples": [ "DSA-5532-1" ] }, "family": { "type": "string", "description": "Distribution family: debian, ubuntu, almalinux, rocky or rhel. New values may be added.", "examples": [ "debian" ] }, "kind": { "description": "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).\n| |\n|---|\n| `cve` A distribution's record of one CVE across its releases, including unfixed ones: DEBIAN-CVE-\u2026 or UBUNTU-CVE-\u2026. |\n| `notice` A security notice that ships fixed packages, usually for several CVEs: DSA, DLA, USN, ALSA, RLSA or RHSA. |\n| `advisory` A package ecosystem's advisory of a vulnerable package: a GitHub (GHSA), Drupal or Packagist (PKSA) security advisory. |\n| `malware` A package published with malicious code, every listed version is affected: MAL-\u2026. |", "$ref": "#\/components\/schemas\/AdvisoryKind" }, "summary": { "type": [ "string", "null" ], "description": "Short title, null for CVE records.", "examples": [ "openssl - security update" ] }, "details": { "type": [ "string", "null" ], "description": "Description, cut to a few hundred characters." }, "severity": { "description": "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.\n| |\n|---|\n| `critical` Ubuntu critical, Red Hat Critical, or a CVSS base score of 9.0 or higher. |\n| `high` Ubuntu high, Red Hat Important, Debian high, or a CVSS base score from 7.0. |\n| `medium` Ubuntu medium, Red Hat Moderate, Debian medium, or a CVSS base score from 4.0. |\n| `low` Ubuntu low, Red Hat Low, Debian low, or a CVSS base score below 4.0. |\n| `negligible` Ubuntu negligible or Debian unimportant: no practical impact on the distribution's builds. |\n| `unknown` Not rated yet. |", "$ref": "#\/components\/schemas\/AdvisorySeverity" }, "cvss": { "type": [ "object", "null" ], "description": "The highest CVSS v3 base score and its vector, null without a CVSS v3 vector.", "properties": { "score": { "type": [ "number", "null" ], "examples": [ 7.5 ] }, "vector": { "type": [ "string", "null" ], "examples": [ "CVSS:3.1\/AV:N\/AC:L\/PR:N\/UI:N\/S:U\/C:H\/I:N\/A:N" ] } }, "required": [ "score", "vector" ] }, "cves": { "type": "array", "description": "CVE IDs the advisory covers.", "examples": [ [ "CVE-2023-5363" ] ], "items": {} }, "aliases": { "type": "array", "description": "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.", "examples": [ [ "CVE-2023-5363", "DEBIAN-CVE-2023-5363" ] ], "items": { "type": "string" } }, "references": { "type": "array", "description": "A few references, advisories and fixes first.", "items": {} }, "url": { "type": "string", "description": "The distribution's page of the advisory, or its OSV.dev page.", "examples": [ "https:\/\/security-tracker.debian.org\/tracker\/DSA-5532" ] }, "published_at": { "type": [ "string", "null" ], "description": "ISO 8601 publication timestamp, null when unknown." }, "modified_at": { "type": "string", "description": "ISO 8601 timestamp of the last change to the advisory." }, "packages": { "type": "array", "description": "Affected packages per imported release with their version range.", "items": { "$ref": "#\/components\/schemas\/AdvisoryPackage" } } }, "required": [ "id", "family", "kind", "summary", "details", "severity", "cvss", "cves", "aliases", "references", "url", "published_at", "modified_at", "packages" ], "title": "Advisory" }, "AdvisoryKind": { "type": "string", "description": "| |\n|---|\n| `cve` A distribution's record of one CVE across its releases, including unfixed ones: DEBIAN-CVE-\u2026 or UBUNTU-CVE-\u2026. |\n| `notice` A security notice that ships fixed packages, usually for several CVEs: DSA, DLA, USN, ALSA, RLSA or RHSA. |\n| `advisory` A package ecosystem's advisory of a vulnerable package: a GitHub (GHSA), Drupal or Packagist (PKSA) security advisory. |\n| `malware` A package published with malicious code, every listed version is affected: MAL-\u2026. |", "x-extensible-enum": [ "cve", "notice", "advisory", "malware" ], "title": "AdvisoryKind" }, "AdvisoryPackage": { "type": "object", "properties": { "release": { "type": "string", "description": "Release such as debian:12, ubuntu:22.04, ubuntu-pro:16.04 (Ubuntu Pro fixes), almalinux:9, rocky:9 or rhel:9.", "examples": [ "debian:12" ] }, "name": { "type": "string", "description": "Package name as the distribution publishes it: the source package for Debian, Ubuntu and Rocky Linux, the binary package for AlmaLinux and Red Hat.", "examples": [ "openssl" ] }, "introduced": { "type": [ "string", "null" ], "description": "First affected version, null when every earlier version is affected." }, "fixed": { "type": [ "string", "null" ], "description": "First fixed version, null when no fix is released for the release.", "examples": [ "3.0.11-1~deb12u2" ] }, "last_affected": { "type": [ "string", "null" ], "description": "Last affected version for a range without a fix, usually null." } }, "required": [ "release", "name", "introduced", "fixed", "last_affected" ], "title": "AdvisoryPackage" }, "AdvisorySeverity": { "type": "string", "description": "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.\n| |\n|---|\n| `critical` Ubuntu critical, Red Hat Critical, or a CVSS base score of 9.0 or higher. |\n| `high` Ubuntu high, Red Hat Important, Debian high, or a CVSS base score from 7.0. |\n| `medium` Ubuntu medium, Red Hat Moderate, Debian medium, or a CVSS base score from 4.0. |\n| `low` Ubuntu low, Red Hat Low, Debian low, or a CVSS base score below 4.0. |\n| `negligible` Ubuntu negligible or Debian unimportant: no practical impact on the distribution's builds. |\n| `unknown` Not rated yet. |", "x-extensible-enum": [ "critical", "high", "medium", "low", "negligible", "unknown" ], "title": "AdvisorySeverity" }, "AgentRelease": { "type": "object", "properties": { "version": { "type": "string", "description": "Stable semantic version.", "examples": [ "1.2.3" ] }, "tag": { "type": "string", "description": "Git tag of the release.", "examples": [ "v1.2.3" ] }, "url": { "type": [ "string", "null" ], "description": "Release notes on GitHub, null for a release added by hand.", "examples": [ "https:\/\/github.com\/chieftools\/serverchief-agent\/releases\/tag\/v1.2.3" ] }, "is_latest": { "type": "boolean", "description": "Whether this is the newest release, the version an agent update installs." }, "published_at": { "type": "string", "description": "ISO 8601 timestamp of the publication." }, "rollout_starts_at": { "type": "string", "description": "ISO 8601 timestamp after which the release is rolled out automatically, 24 hours after its publication by default." } }, "required": [ "version", "tag", "url", "is_latest", "published_at", "rollout_starts_at" ], "title": "AgentRelease" }, "AgentUpdateResult": { "type": "string", "description": "The `code` an agent reports in the result of an `update_agent` command, see \"Agent updates\" in the agent protocol.\n| |\n|---|\n| `updated` The target version is installed and running. |\n| `install_failed` The package manager failed, the previous version is still installed. |\n| `readiness_failed_rolled_back` The new version did not become ready, the previous version was reinstalled and runs again. |\n| `rollback_failed` The new version did not become ready and reinstalling the previous version failed too. |\n| `target_unavailable` The package repository does not offer the target version. |\n| `rollback_unavailable` The package repository does not offer the installed version, which a rollback needs, so the update was not attempted. |\n| `package_manager_busy` Another process held the package manager lock for an hour. |\n| `unsupported_install` The agent was not installed from the Server Chief package and repository. |", "x-extensible-enum": [ "updated", "install_failed", "readiness_failed_rolled_back", "rollback_failed", "target_unavailable", "rollback_unavailable", "package_manager_busy", "unsupported_install" ], "title": "AgentUpdateResult" }, "Alert": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted alert ID.", "examples": [ "alert_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "status": { "description": "firing until two evaluations in a row no longer breach the rule, then resolved.", "$ref": "#\/components\/schemas\/AlertStatus" }, "server": { "type": "object", "description": "The server the alert is about.", "properties": { "id": { "type": "string", "description": "Formatted server ID.", "examples": [ "server_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "web-01" ] } }, "required": [ "id", "name" ] }, "rule_id": { "type": [ "string", "null" ], "description": "Formatted ID of the rule that raised it, null once the rule was deleted.", "examples": [ "rule_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "rule_description": { "type": "string", "description": "What the rule said when the alert fired.", "examples": [ "Disk space used above 90% for 10 minutes" ] }, "metric": { "$ref": "#\/components\/schemas\/AlertMetric" }, "condition": { "$ref": "#\/components\/schemas\/AlertCondition" }, "duration_minutes": { "type": "integer", "examples": [ 10 ] }, "instance": { "type": [ "string", "null" ], "description": "The mount point, disk or interface, null for a server-wide value.", "examples": [ "\/var" ] }, "unit": { "type": "string", "description": "Unit of the values, such as %, Mbit\/s or minutes. Empty for a plain number.", "enum": [ "Mbit\/s", "MB\/s", "IOPS", "packets\/s", "per second", "minutes", "", "%" ], "examples": [ "%" ] }, "baseline_value": { "type": [ "number", "null" ], "description": "The normal level the value was compared to when the alert fired, null for a fixed threshold.", "examples": [ 120.5 ] }, "threshold_value": { "type": [ "number", "null" ], "description": "The value the metric had to stay above or below when the alert fired, null for alerts from before it was kept.", "examples": [ 90 ] }, "value": { "type": "number", "description": "The newest value of the rule's window while it fired.", "examples": [ 93.2 ] }, "peak_value": { "type": "number", "description": "The worst value while it was firing: the highest for above rules, the lowest for below rules.", "examples": [ 95.1 ] }, "description": { "type": "string", "description": "The alert in words.", "examples": [ "Disk space used on \/var is 93.2%" ] }, "fired_at": { "type": "string", "description": "ISO 8601 time the rule fired." }, "resolved_at": { "type": [ "string", "null" ], "description": "ISO 8601 time the alert resolved, null while it fires." }, "closed_reason": { "type": [ "string", "null" ], "description": "Why it closed without the metric recovering, null when it recovered or still fires." } }, "required": [ "id", "status", "server", "rule_id", "rule_description", "metric", "condition", "duration_minutes", "instance", "unit", "baseline_value", "threshold_value", "value", "peak_value", "description", "fired_at", "resolved_at", "closed_reason" ], "title": "Alert" }, "AlertBaseline": { "type": "string", "description": "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.\n", "x-extensible-enum": [ "time_of_day" ], "title": "AlertBaseline" }, "AlertCondition": { "type": "string", "enum": [ "above", "below" ], "title": "AlertCondition" }, "AlertFiredEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A metric alert rule fired.", "enum": [ "alert.fired" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Alert" } }, "required": [ "object" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "AlertFiredEvent" }, "AlertMetric": { "type": "string", "description": "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.\n", "x-extensible-enum": [ "cpu_used", "cpu_iowait", "cpu_steal", "load_per_core", "memory_used", "swap_used", "disk_space_used", "inodes_used", "disk_busy", "disk_read", "disk_write", "disk_operations", "network_in", "network_out", "packets_in", "packets_out", "network_errors", "tcp_connections", "tcp_time_wait", "processes_blocked", "threads", "uptime" ], "title": "AlertMetric" }, "AlertResolvedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A firing alert resolved.", "enum": [ "alert.resolved" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Alert" }, "reason": { "description": "Why the alert closed, only `recovered` means the problem went away. Handle unknown reasons like a closed alert.\n| |\n|---|\n| `recovered` The metric stayed within the rule for two checks in a row, the only reason the problem went away. |\n| `out_of_scope` The rule no longer covers the server, or the server stopped collecting metrics. |\n| `rule_changed` Someone changed the rule, alerts it opens from now on follow the new rule. |\n| `rule_disabled` Someone turned the rule off. |\n| `rule_deleted` Someone deleted the rule. |", "$ref": "#\/components\/schemas\/AlertResolvedReason" } }, "required": [ "object", "reason" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "AlertResolvedEvent" }, "AlertResolvedReason": { "type": "string", "description": "Why a metric alert closed, sent as `data.reason` of the `alert.resolved` webhook.\n| |\n|---|\n| `recovered` The metric stayed within the rule for two checks in a row, the only reason the problem went away. |\n| `out_of_scope` The rule no longer covers the server, or the server stopped collecting metrics. |\n| `rule_changed` Someone changed the rule, alerts it opens from now on follow the new rule. |\n| `rule_disabled` Someone turned the rule off. |\n| `rule_deleted` Someone deleted the rule. |", "x-extensible-enum": [ "recovered", "out_of_scope", "rule_changed", "rule_disabled", "rule_deleted" ], "title": "AlertResolvedReason" }, "AlertRule": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted alert rule ID.", "examples": [ "rule_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "metric": { "description": "What the rule watches.", "$ref": "#\/components\/schemas\/AlertMetric" }, "condition": { "$ref": "#\/components\/schemas\/AlertCondition" }, "threshold": { "type": "number", "description": "Threshold in the metric's unit, or for a baseline rule the percentage above or below the normal level.", "examples": [ 90 ] }, "baseline": { "anyOf": [ { "description": "The normal level the rule compares to, null for a fixed threshold.", "$ref": "#\/components\/schemas\/AlertBaseline" }, { "type": "null" } ] }, "minimum_difference": { "type": [ "number", "null" ], "description": "For a baseline rule: how much the value must at least differ from normal, in the metric's unit. Null for any difference.", "examples": [ 10 ] }, "unit": { "type": "string", "description": "Unit of the threshold and alert values, such as %, Mbit\/s or minutes. Empty for a plain number.", "enum": [ "Mbit\/s", "MB\/s", "IOPS", "packets\/s", "per second", "minutes", "", "%" ], "examples": [ "%" ] }, "duration_minutes": { "type": "integer", "description": "Minutes the metric must stay above or below the threshold (or the normal level) before the rule fires.", "examples": [ 10 ] }, "scope": { "description": "all for every server of the team, tag for the servers with a tag, servers for the chosen servers.", "$ref": "#\/components\/schemas\/AlertScope" }, "exclude": { "type": "boolean", "description": "For tag and servers rules: watch the servers without the tag, or all servers except the chosen ones." }, "tag": { "anyOf": [ { "description": "The tag of a tag rule, null for other rules and when the tag was deleted.", "$ref": "#\/components\/schemas\/ServerTag" }, { "type": "null" } ] }, "servers": { "type": "array", "description": "The chosen servers of a servers rule, empty for other rules.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted server ID.", "examples": [ "server_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "web-01" ] } }, "required": [ "id", "name" ] } }, "instance": { "type": [ "string", "null" ], "description": "The mount point, disk or interface the rule watches, null for all mount points or the host total of disks and interfaces.", "examples": [ "\/var" ] }, "enabled": { "type": "boolean", "description": "Whether the rule is evaluated. Turning it off closes its open alerts." }, "description": { "type": "string", "description": "The rule in words.", "examples": [ "Disk space used above 90% for 10 minutes" ] }, "scope_description": { "type": "string", "description": "Where the rule applies, in words.", "examples": [ "Servers tagged production" ] }, "firing_alerts_count": { "type": "integer", "description": "Alerts of the rule that are firing.", "examples": [ 1 ] }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "metric", "condition", "threshold", "baseline", "minimum_difference", "unit", "duration_minutes", "scope", "exclude", "tag", "servers", "instance", "enabled", "description", "scope_description", "firing_alerts_count", "created_at", "updated_at" ], "title": "AlertRule" }, "AlertScope": { "type": "string", "description": "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.\n", "x-extensible-enum": [ "all", "tag", "servers" ], "title": "AlertScope" }, "AlertStatus": { "type": "string", "x-extensible-enum": [ "firing", "resolved" ], "title": "AlertStatus" }, "Application": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted application ID.", "examples": [ "application_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "server": { "type": "object", "description": "The server the application runs on.", "properties": { "id": { "type": "string", "description": "Formatted server ID.", "examples": [ "server_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "web-01" ] } }, "required": [ "id", "name" ] }, "path": { "type": "string", "description": "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\/.", "examples": [ "\/home\/forge\/shop.example.com\/current" ] }, "kind": { "description": "What the application is: the first of WordPress, Laravel and Symfony that matches, else a Composer or npm project.", "$ref": "#\/components\/schemas\/ApplicationKind" }, "version": { "type": [ "string", "null" ], "description": "The WordPress, Laravel (laravel\/framework) or Symfony (symfony\/http-kernel) version, null for other kinds or when it cannot be read.", "examples": [ "11.9.2" ] }, "end_of_life": { "type": "boolean", "description": "Whether the WordPress, Laravel or Symfony release is past its end of life according to endoflife.date." }, "end_of_life_at": { "type": [ "string", "null" ], "description": "Date the release reaches or reached its end of life, null when endoflife.date has no date.", "examples": [ "2026-03-12" ] }, "latest_version": { "type": [ "string", "null" ], "description": "The latest WordPress release, null for other kinds or while it is unknown.", "examples": [ "6.8.3" ] }, "outdated": { "type": [ "boolean", "null" ], "description": "Whether WordPress is older than its latest release, null for other kinds or when it cannot be told." }, "sites": { "type": "array", "description": "Names of the sites it serves, sorted.", "examples": [ [ "shop.example.com", "www.shop.example.com" ] ], "items": { "type": "string" } }, "owner": { "type": [ "string", "null" ], "description": "The Plesk subscription, DirectAdmin user or home directory owner of its first site, null when unknown.", "examples": [ "forge" ] }, "lockfiles": { "type": "array", "description": "The lockfiles read at the application root.", "examples": [ [ "composer.lock", "package-lock.json" ] ], "items": { "type": "string" } }, "packages_count": { "type": "integer", "description": "Composer and npm packages of its lockfiles, development dependencies included.", "examples": [ 214 ] }, "plugins_count": { "type": "integer", "description": "WordPress plugins, must-use plugins included.", "examples": [ 15 ] }, "themes_count": { "type": "integer", "description": "WordPress themes.", "examples": [ 2 ] }, "truncated": { "type": "boolean", "description": "Whether packages, plugins or themes were left out because the agent's limits were reached." }, "open_vulnerabilities_count": { "type": "integer", "description": "Open vulnerabilities of packages it needs in production.", "examples": [ 3 ] }, "malicious_packages_count": { "type": "integer", "description": "Open malicious packages, in production or development dependencies.", "examples": [ 0 ] }, "detected_at": { "type": "string", "description": "ISO 8601 timestamp the agent first reported the application." } }, "required": [ "id", "path", "kind", "version", "end_of_life", "end_of_life_at", "latest_version", "outdated", "sites", "owner", "lockfiles", "packages_count", "plugins_count", "themes_count", "truncated", "detected_at" ], "title": "Application" }, "ApplicationEcosystem": { "type": "string", "description": "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.\n", "x-extensible-enum": [ "composer", "npm", "wordpress-plugin", "wordpress-theme", "wordpress-core" ], "title": "ApplicationEcosystem" }, "ApplicationKind": { "type": "string", "description": "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.\n", "x-extensible-enum": [ "wordpress", "laravel", "symfony", "composer", "node" ], "title": "ApplicationKind" }, "ApplicationPackage": { "type": "object", "properties": { "ecosystem": { "description": "composer or npm for a package of a lockfile, wordpress-plugin or wordpress-theme for a WordPress plugin or theme.", "$ref": "#\/components\/schemas\/ApplicationEcosystem" }, "name": { "type": "string", "description": "The package name, or a plugin's or theme's directory (its slug).", "examples": [ "guzzlehttp\/guzzle" ] }, "version": { "type": [ "string", "null" ], "description": "The installed version, null when a plugin or theme header names none.", "examples": [ "7.9.2" ] }, "title": { "type": [ "string", "null" ], "description": "A plugin's or theme's name from its header, null for packages.", "examples": [ "Akismet Anti-spam" ] }, "direct": { "type": "boolean", "description": "Whether composer.json or package.json requires the package itself rather than another package." }, "dev": { "type": "boolean", "description": "Whether only development dependencies need the package." }, "must_use": { "type": "boolean", "description": "Whether the plugin is a must-use plugin, which WordPress always loads." }, "parent": { "type": [ "string", "null" ], "description": "The parent theme of a child theme.", "examples": [ "twentytwentyfour" ] }, "latest_version": { "type": [ "string", "null" ], "description": "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.", "examples": [ "7.9.2" ] }, "latest_released_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp the latest stable release was published, when the registry tells." }, "outdated": { "type": [ "boolean", "null" ], "description": "Whether the installed version is older than the latest stable release, null when it cannot be told." } }, "required": [ "ecosystem", "name", "version", "title", "direct", "dev", "must_use", "parent", "latest_version", "latest_released_at", "outdated" ], "title": "ApplicationPackage" }, "ApplicationVulnerability": { "type": "object", "properties": { "vulnerability_id": { "type": "string", "description": "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.", "examples": [ "CVE-2022-31090" ] }, "advisory_id": { "type": "string", "description": "The most severe advisory covering it.", "examples": [ "GHSA-25mq-v84q-4j7r" ] }, "advisory_ids": { "type": "array", "description": "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).", "examples": [ [ "GHSA-25mq-v84q-4j7r" ] ], "items": { "type": "string" } }, "advisory_url": { "type": "string", "description": "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\/.", "examples": [ "https:\/\/github.com\/advisories\/GHSA-25mq-v84q-4j7r" ] }, "summary": { "type": [ "string", "null" ], "description": "Summary of the deciding advisory, or the start of its description.", "examples": [ "CURLOPT_HTTPAUTH option not cleared on change of origin" ] }, "ecosystem": { "description": "composer, npm, wordpress-plugin, wordpress-theme, or wordpress-core for WordPress itself (package wordpress).", "$ref": "#\/components\/schemas\/ApplicationEcosystem" }, "package": { "type": "string", "examples": [ "guzzlehttp\/guzzle" ] }, "installed_version": { "type": "string", "examples": [ "7.4.0" ] }, "fixed_version": { "type": [ "string", "null" ], "description": "The lowest release that fixes it above the installed version, null without a fix and always for a malicious package.", "examples": [ "7.4.5" ] }, "fix_status": { "description": "available when a fixed release exists, none without one.\n| |\n|---|\n| `available` The package manager offers an update to the fixed version or later, installing pending updates fixes it. |\n| `reboot` A newer installed kernel fixes it, rebooting into that kernel does. |\n| `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). |\n| `none` The distribution has not released a fix for the server's release. |", "$ref": "#\/components\/schemas\/VulnerabilityFixStatus" }, "severity": { "description": "GitHub's or Wordfence's rating of the advisory, otherwise the CVSS v3 band. Malicious packages are critical.\n| |\n|---|\n| `critical` Ubuntu critical, Red Hat Critical, or a CVSS base score of 9.0 or higher. |\n| `high` Ubuntu high, Red Hat Important, Debian high, or a CVSS base score from 7.0. |\n| `medium` Ubuntu medium, Red Hat Moderate, Debian medium, or a CVSS base score from 4.0. |\n| `low` Ubuntu low, Red Hat Low, Debian low, or a CVSS base score below 4.0. |\n| `negligible` Ubuntu negligible or Debian unimportant: no practical impact on the distribution's builds. |\n| `unknown` Not rated yet. |", "$ref": "#\/components\/schemas\/AdvisorySeverity" }, "cvss_score": { "type": [ "number", "null" ], "description": "Highest CVSS v3 base score of the advisories, null without a CVSS v3 vector.", "examples": [ 7.7 ] }, "malicious": { "type": "boolean", "description": "Whether the package was published with malicious code: remove it and check the server." }, "dev": { "type": "boolean", "description": "Whether only development dependencies need the package. Such vulnerabilities are not counted or alerted on." }, "known_exploited": { "type": "boolean", "description": "Whether CISA lists the CVE in its Known Exploited Vulnerabilities catalog." }, "known_exploited_at": { "type": [ "string", "null" ], "description": "Date CISA added the CVE to its Known Exploited Vulnerabilities catalog, null when it is not listed.", "examples": [ "2026-10-27" ] }, "epss_score": { "type": [ "number", "null" ], "description": "FIRST's EPSS score: the probability of exploitation activity in the next 30 days, 0 to 1.", "examples": [ 0.01947 ] }, "epss_percentile": { "type": [ "number", "null" ], "description": "How the EPSS score ranks among all scored CVEs, 0 to 1.", "examples": [ 0.83121 ] }, "public_exploit": { "type": "boolean", "description": "Whether Metasploit, Nuclei or Exploit-DB has a public exploit of the CVE, so attacking it takes little skill." }, "metasploit_module": { "type": [ "string", "null" ], "description": "Full name of a Metasploit Framework exploit or auxiliary module attacking the CVE, null when there is none.", "examples": [ "exploit\/linux\/http\/magento_xxe_to_glibc_buf_overflow" ] }, "nuclei_template": { "type": [ "string", "null" ], "description": "Path of a Nuclei template detecting the CVE in ProjectDiscovery's nuclei-templates repository, null when there is none.", "examples": [ "http\/cves\/2021\/CVE-2021-44228.yaml" ] }, "exploit_db_id": { "type": [ "integer", "null" ], "description": "ID of an exploit or proof of concept of the CVE on Exploit-DB, null when there is none.", "examples": [ 50973 ] }, "first_seen_at": { "type": "string", "description": "ISO 8601 timestamp the vulnerability was first found in the application." }, "resolved_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp the vulnerability was resolved, null while it is open." }, "resolved_version": { "type": [ "string", "null" ], "description": "Version of the package when the vulnerability was resolved, null when the package was removed or it is open.", "examples": [ "7.4.5" ] } }, "required": [ "vulnerability_id", "advisory_id", "advisory_ids", "advisory_url", "summary", "ecosystem", "package", "installed_version", "fixed_version", "fix_status", "severity", "cvss_score", "malicious", "dev", "known_exploited", "known_exploited_at", "epss_score", "epss_percentile", "public_exploit", "metasploit_module", "nuclei_template", "exploit_db_id", "first_seen_at", "resolved_at", "resolved_version" ], "title": "ApplicationVulnerability" }, "CertificateIssue": { "type": "string", "description": "A check a certificate fails, computed on ingest by `Services\\Certificates\\Checks`.\n| |\n|---|\n| `expiring_unmanaged` Expires within the warning window, or expired, and no renewal automation was found. |\n| `renewal_missing` Issued by certbot or acme.sh, but no timer or cron job renews it. |\n| `staging_ca` Issued by a staging CA such as Let's Encrypt staging, which browsers do not trust. |\n| `self_signed_public` Self-signed and used by a site with a public domain name. |\n| `incomplete_chain` The leaf does not verify to a trusted root with the intermediates found next to it. |\n| `weak_key` An RSA key below 2048 bits or an EC curve below P-256. |\n| `names_not_covered` Names of a site using it that the certificate does not cover. |\n| `duplicate` Another certificate on the server covers the same names and is newer. |", "x-extensible-enum": [ "expiring_unmanaged", "renewal_missing", "staging_ca", "self_signed_public", "incomplete_chain", "weak_key", "names_not_covered", "duplicate" ], "title": "CertificateIssue" }, "CertificateIssueDetails": { "type": "object", "properties": { "issue": { "description": "The check the certificate fails.\n| |\n|---|\n| `expiring_unmanaged` Expires within the warning window, or expired, and no renewal automation was found. |\n| `renewal_missing` Issued by certbot or acme.sh, but no timer or cron job renews it. |\n| `staging_ca` Issued by a staging CA such as Let's Encrypt staging, which browsers do not trust. |\n| `self_signed_public` Self-signed and used by a site with a public domain name. |\n| `incomplete_chain` The leaf does not verify to a trusted root with the intermediates found next to it. |\n| `weak_key` An RSA key below 2048 bits or an EC curve below P-256. |\n| `names_not_covered` Names of a site using it that the certificate does not cover. |\n| `duplicate` Another certificate on the server covers the same names and is newer. |", "$ref": "#\/components\/schemas\/CertificateIssue" }, "severity": { "description": "How urgent it is.\n| |\n|---|\n| `high` Visitors or mail clients get errors now or soon: an expiring certificate nobody renews, an untrusted CA. |\n| `medium` Some clients fail or the certificate is weaker than it should be. |\n| `low` Housekeeping, nothing breaks. |", "$ref": "#\/components\/schemas\/CertificateIssueSeverity" }, "label": { "type": "string", "enum": [ "Expiring, not renewed", "Renewal missing", "Staging CA", "Self-signed on a public site", "Incomplete chain", "Weak key", "Names not covered", "Duplicate" ], "examples": [ "Weak key" ] }, "explanation": { "type": "string", "description": "What is wrong and what to do about it.", "enum": [ "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." ], "examples": [ "The key is weaker than an RSA 2048-bit or P-256 key, which clients may reject. Issue it again with a stronger key." ] } }, "required": [ "issue", "severity", "label", "explanation" ], "title": "CertificateIssueDetails" }, "CertificateIssueSeverity": { "type": "string", "description": "| |\n|---|\n| `high` Visitors or mail clients get errors now or soon: an expiring certificate nobody renews, an untrusted CA. |\n| `medium` Some clients fail or the certificate is weaker than it should be. |\n| `low` Housekeeping, nothing breaks. |", "x-extensible-enum": [ "high", "medium", "low" ], "title": "CertificateIssueSeverity" }, "CertificateManager": { "type": "string", "description": "The tool that issued and renews a certificate, from the agent's `managed_by.tool`.\n", "x-extensible-enum": [ "certbot", "acme.sh", "plesk", "directadmin", "forge" ], "title": "CertificateManager" }, "CertificateRenewal": { "type": "string", "description": "The renewal automation the agent found for a certificate, from `managed_by.renewal`.\n| |\n|---|\n| `timer` A systemd timer, such as certbot.timer. |\n| `cron` A cron job, such as `certbot renew` or `acme.sh --cron`. |\n| `panel` The hosting panel renews it. |\n| `none` No renewal automation was found. |", "x-extensible-enum": [ "timer", "cron", "panel", "none" ], "title": "CertificateRenewal" }, "CertificateUsage": { "type": "string", "description": "What uses a certificate, from the agent's `used_by[].kind`.\n| |\n|---|\n| `site` A site, its ref is the vhost key `source\/name`. |\n| `postfix` |\n| `dovecot` |\n| `exim` |\n| `panel` The hosting panel's own interface. |\n| `other` Another service, named by its ref. |", "x-extensible-enum": [ "site", "postfix", "dovecot", "exim", "panel", "other" ], "title": "CertificateUsage" }, "CertificateUsedBy": { "type": "object", "properties": { "kind": { "description": "What uses the certificate.\n| |\n|---|\n| `site` A site, its ref is the vhost key `source\/name`. |\n| `postfix` |\n| `dovecot` |\n| `exim` |\n| `panel` The hosting panel's own interface. |\n| `other` Another service, named by its ref. |", "$ref": "#\/components\/schemas\/CertificateUsage" }, "ref": { "type": "string", "description": "The vhost key (`source\/name`) for a site, the service name otherwise.", "examples": [ "apache\/shop.example.com" ] }, "site_url": { "type": [ "string", "null" ], "description": "The site's page in Server Chief, null for services.", "examples": [ "https:\/\/server.chief.app\/team\/acme\/sites\/01j8q8zk2f4m6n7p9r1s3t5v7x\/shop.example.com" ] } }, "required": [ "kind", "ref", "site_url" ], "title": "CertificateUsedBy" }, "CreateInstallCommandRequest": { "type": "object", "properties": { "single_use": { "type": "boolean", "description": "Whether the command adds one server, or any number of servers until it expires.", "default": true }, "valid_for_hours": { "type": "integer", "description": "Hours the command can add servers, at most 24.", "default": 1, "minimum": 1, "maximum": 24 }, "description": { "type": [ "string", "null" ], "description": "What the command is for, shown with the active install commands.", "examples": [ "Web servers in Frankfurt" ], "maxLength": 255 }, "tags": { "type": "array", "description": "Tags of the team every added server gets, by formatted ID or by name.", "examples": [ [ "production", "tag_01j8q8zk2f4m6n7p9r1s3t5v7x" ] ], "items": { "type": "string", "maxLength": 64 }, "maxItems": 50, "uniqueItems": true } }, "title": "CreateInstallCommandRequest" }, "CreateWebhookEndpointRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS URL that receives the events, it must resolve to a public address.", "examples": [ "https:\/\/example.com\/webhooks\/chief" ], "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "description": "What the endpoint is for, shown in the dashboard.", "examples": [ "Paging" ], "maxLength": 255 }, "events": { "type": "array", "description": "Event types the endpoint receives, `*` for every event including types added later.", "examples": [ [ "server.offline", "server.online" ] ], "items": { "type": "string", "enum": [ "*", "server.created", "server.enrolled", "server.updated", "server.deleted", "server.offline", "server.online", "server.reboot_stalled", "alert.fired", "alert.resolved", "metrics.stalled", "metrics.resumed", "server.storage_unhealthy", "server.storage_healthy" ] }, "minItems": 1, "uniqueItems": true } }, "required": [ "url", "events" ], "title": "CreateWebhookEndpointRequest" }, "InstallCommand": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted install command ID.", "examples": [ "install_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "token": { "type": [ "string", "null" ], "description": "One-time view of the enrollment token, only in the response that creates the command. Store it or run the command right away.", "examples": [ "scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE" ] }, "install_command": { "type": [ "string", "null" ], "description": "Shell command that installs the agent and adds the server, run as root on each server. Only in the response that creates it.", "examples": [ "curl -fsSL https:\/\/pkg.server.chief.app\/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE" ] }, "status": { "description": "active while it can add servers, used once a single-use command added its server, or expired or revoked.", "$ref": "#\/components\/schemas\/InstallCommandStatus" }, "description": { "type": [ "string", "null" ], "examples": [ "Web servers in Frankfurt" ] }, "single_use": { "type": "boolean", "description": "Whether it adds one server, or any number of servers until it expires." }, "servers_added": { "type": "integer", "description": "Servers added with it.", "examples": [ 2 ] }, "tags": { "type": "array", "description": "Tags every added server gets.", "items": { "$ref": "#\/components\/schemas\/ServerTag" } }, "expires_at": { "type": "string", "description": "ISO 8601 timestamp after which it no longer adds servers." }, "last_used_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the last server it added, null before the first." }, "revoked_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp it was revoked, null unless revoked." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." } }, "required": [ "id", "status", "description", "single_use", "servers_added", "tags", "expires_at", "last_used_at", "revoked_at", "created_at" ], "title": "InstallCommand" }, "InstallCommandStatus": { "type": "string", "x-extensible-enum": [ "active", "used", "expired", "revoked" ], "title": "InstallCommandStatus" }, "InventoryDataset": { "type": "string", "description": "Inventory datasets readable as the agent reported them. Packages, sites, certificates and repositories have their own paginated endpoints instead.\n| |\n|---|\n| `system` Hostname, operating system, kernel, virtualization, boot time, timezone and PHP builds. |\n| `hardware` CPU, memory, swap, disks and file systems. |\n| `storage` Software RAID arrays with their members, ZFS pools with their vdevs, scrubs and volumes, and the state of NVMe and SCSI disks. |\n| `network` Network interfaces, addresses and default routes. |\n| `resolvers` Nameservers and search domains. |\n| `cloud` Cloud provider, region and instance type from the provider's metadata service. |\n| `updates` Pending updates, whether a reboot is required and when the package lists were refreshed. |", "x-extensible-enum": [ "system", "hardware", "storage", "network", "resolvers", "cloud", "updates" ], "title": "InventoryDataset" }, "MetricPoint": { "type": "object", "properties": { "at": { "type": "string", "description": "ISO 8601 start of the bucket." }, "avg": { "type": "number", "description": "Average of the bucket's samples.", "examples": [ 12.5 ] }, "min": { "type": "number", "description": "Lowest sample of the bucket." }, "max": { "type": "number", "description": "Highest sample of the bucket." } }, "required": [ "at", "avg", "min", "max" ], "title": "MetricPoint" }, "MetricSeries": { "type": "object", "properties": { "metric": { "type": "string", "description": "Stored metric name.", "examples": [ "cpu.user" ] }, "instance": { "type": [ "string", "null" ], "description": "The mount point, disk or interface, null for a server-wide value or the host total of disks and interfaces.", "examples": [ "eth0" ] }, "unit": { "anyOf": [ { "description": "Unit of the values.", "$ref": "#\/components\/schemas\/MetricUnit" }, { "type": "null" } ] }, "points": { "type": "array", "description": "Buckets oldest first: the average, lowest and highest sample of each. Buckets without samples are left out.", "items": { "$ref": "#\/components\/schemas\/MetricPoint" } } }, "required": [ "metric", "instance", "unit", "points" ], "title": "MetricSeries" }, "MetricUnit": { "type": "string", "description": "The unit a stored metric is sent in (metrics protocol, \"Metric catalog\").\n", "x-extensible-enum": [ "percent", "count", "load", "bytes", "bytes_per_second", "per_second", "seconds" ], "title": "MetricUnit" }, "MetricValue": { "type": "object", "properties": { "metric": { "type": "string", "description": "Stored metric name. New metrics may be added.", "examples": [ "fs.used_pct" ] }, "instance": { "type": [ "string", "null" ], "description": "The mount point, disk or interface, null for a server-wide value or the host total of disks and interfaces.", "examples": [ "\/var" ] }, "unit": { "anyOf": [ { "description": "Unit of the value. Rates are per second over the minute before the sample.", "$ref": "#\/components\/schemas\/MetricUnit" }, { "type": "null" } ] }, "value": { "type": "number", "examples": [ 41.5 ] }, "at": { "type": "string", "description": "ISO 8601 time of the sample." } }, "required": [ "metric", "instance", "unit", "value", "at" ], "title": "MetricValue" }, "MetricsResumedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A server delivers metrics again.", "enum": [ "metrics.resumed" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Server" }, "stalled_at": { "type": "string", "format": "date-time", "description": "When Server Chief first noticed that metrics stopped arriving." } }, "required": [ "object", "stalled_at" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "MetricsResumedEvent" }, "MetricsStalledEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "An online server stopped delivering metrics.", "enum": [ "metrics.stalled" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Server" }, "stalled_at": { "type": "string", "format": "date-time", "description": "When Server Chief first noticed that metrics stopped arriving." } }, "required": [ "object", "stalled_at" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "MetricsStalledEvent" }, "PackageOriginKind": { "type": "string", "description": "Where an installed package version comes from, derived from its `origins` and the server's repositories.\n| |\n|---|\n| `distro` A distribution repository offers the installed version, security advisories cover it. |\n| `third_party` Only third-party repositories offer it, distribution advisories do not cover it. |\n| `none` No configured repository offers it: a manually installed package, a removed repository or a superseded version. |\n| `unknown` The agent could not tell, or the repositories are not known yet. |", "x-extensible-enum": [ "distro", "third_party", "none", "unknown" ], "title": "PackageOriginKind" }, "PackageUpgradeResult": { "type": "string", "description": "The `code` an agent reports in the result of an `upgrade_packages` command, see \"Package updates\" in the agent protocol.\n| |\n|---|\n| `upgraded` The updates of the scope were installed. |\n| `nothing_to_upgrade` No update of the scope was pending. |\n| `upgrade_failed` The package manager failed, the output shows why. Some updates may have been installed. |\n| `dpkg_interrupted` dpkg reports an interrupted install, which someone has to finish with `dpkg --configure -a` first. |\n| `security_unavailable` The repositories have no security metadata, so security updates cannot be told apart. |\n| `package_manager_busy` A package manager held its lock for an hour. |\n| `too_late` The updates were not started before the `not_after` deadline, such as the end of a maintenance window. |\n| `disabled` The server's operator turned installing updates off with `serverchief disable upgrade_packages`. |\n| `unsupported` The agent cannot install updates on this server, the detail says why. |", "x-extensible-enum": [ "upgraded", "nothing_to_upgrade", "upgrade_failed", "dpkg_interrupted", "security_unavailable", "package_manager_busy", "too_late", "disabled", "unsupported" ], "title": "PackageUpgradeResult" }, "PackageUpgradeScope": { "type": "string", "description": "Which pending updates an `upgrade_packages` command installs, see \"Package updates\" in the agent protocol.\n| |\n|---|\n| `security` The pending updates the agent marks as security updates. |\n| `all` Every pending update. |", "x-extensible-enum": [ "security", "all" ], "title": "PackageUpgradeScope" }, "RebootResult": { "type": "string", "description": "The `code` an agent reports in the result of a `reboot` command, see \"Reboots\" in the agent protocol.\n| |\n|---|\n| `rebooted` The server rebooted and the agent started again. |\n| `disabled` The server's operator turned reboots off with `serverchief disable reboot`. |\n| `unsupported` The agent cannot reboot this server, the detail says why. |\n| `package_manager_busy` A package manager held its lock for 15 minutes, the server was not rebooted. |\n| `reboot_failed` Scheduling the reboot failed, the output shows why. |\n| `not_rebooted` The reboot was scheduled but the server did not reboot within 10 minutes, someone may have cancelled it. |\n| `too_late` The reboot was not started before its `not_after` deadline, such as the end of a maintenance window. |\n| `not_required` A reboot only when required found the server did not need one, so it did not reboot. |\n| `required_unknown` A reboot only when required could not tell whether the server needs one, so it did not reboot. |", "x-extensible-enum": [ "rebooted", "disabled", "unsupported", "package_manager_busy", "reboot_failed", "not_rebooted", "too_late", "not_required", "required_unknown" ], "title": "RebootResult" }, "RefreshServerRequest": { "type": "object", "properties": { "datasets": { "type": [ "array", "null" ], "description": "Datasets to collect, or null for every enabled dataset.", "examples": [ [ "packages", "updates" ] ], "items": { "type": "string", "enum": [ "applications", "certificates", "cloud", "hardware", "network", "packages", "repositories", "resolvers", "storage", "system", "updates", "vhosts" ] }, "minItems": 1, "uniqueItems": true } }, "title": "RefreshServerRequest" }, "RemoteAction": { "type": "string", "description": "An action that changes the server, which its operator can turn off on the server with `serverchief disable `, see \"Operator opt-out\" in the agent protocol. The agent then lists it in `capabilities.disabled`.\n| |\n|---|\n| `reboot` Reboot the server. |\n| `upgrade_packages` Install package updates, the agent's own package first. |", "x-extensible-enum": [ "reboot", "upgrade_packages" ], "title": "RemoteAction" }, "ReplaceServerTagsRequest": { "type": "object", "properties": { "tags": { "type": "array", "description": "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.", "examples": [ [ "production", "web" ] ], "items": { "type": "string", "maxLength": 64 }, "maxItems": 50, "uniqueItems": true } }, "required": [ "tags" ], "title": "ReplaceServerTagsRequest" }, "RepositoryIssue": { "type": "string", "description": "A check an enabled package repository fails, computed on ingest by `Services\\Repositories\\Checks`.\n| |\n|---|\n| `insecure_trusted` apt `[trusted=yes]`: signatures are not checked at all. |\n| `unsigned` rpm `gpgcheck=0`: package signatures are not checked. |\n| `plain_http` Fetched over plain HTTP. Signed indexes still protect the content, but not against replaying old indexes or watching what is installed. |\n| `eol_mirror` An archive of an end-of-life release, which receives no updates. Informational. |", "x-extensible-enum": [ "insecure_trusted", "unsigned", "plain_http", "eol_mirror" ], "title": "RepositoryIssue" }, "RepositoryIssueDetails": { "type": "object", "properties": { "issue": { "description": "The check the repository fails.\n| |\n|---|\n| `insecure_trusted` apt `[trusted=yes]`: signatures are not checked at all. |\n| `unsigned` rpm `gpgcheck=0`: package signatures are not checked. |\n| `plain_http` Fetched over plain HTTP. Signed indexes still protect the content, but not against replaying old indexes or watching what is installed. |\n| `eol_mirror` An archive of an end-of-life release, which receives no updates. Informational. |", "$ref": "#\/components\/schemas\/RepositoryIssue" }, "informational": { "type": "boolean", "description": "Whether it only informs, such as an end-of-life archive, and is not counted as a problem." }, "label": { "type": "string", "enum": [ "Trusted without signature", "Signature check off", "Plain HTTP", "End-of-life archive" ], "examples": [ "Trusted without signature" ] }, "explanation": { "type": "string", "description": "What is wrong and what to do about it.", "enum": [ "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." ], "examples": [ "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." ] } }, "required": [ "issue", "informational", "label", "explanation" ], "title": "RepositoryIssueDetails" }, "RepositoryVendorKind": { "type": "string", "description": "Who publishes a package repository, from the vendor classification in `serverchief.repositories.vendors`.\n| |\n|---|\n| `distro` The distribution's own archives, security advisories cover their packages. |\n| `third_party` Anyone else: Sury, NodeSource, Docker, PPAs, a vendor's own repository or an unknown host. |", "x-extensible-enum": [ "distro", "third_party" ], "title": "RepositoryVendorKind" }, "ResendWebhookEventRequest": { "type": "object", "properties": { "endpoint": { "type": "string", "description": "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.", "examples": [ "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6" ] } }, "required": [ "endpoint" ], "title": "ResendWebhookEventRequest" }, "RotateWebhookSecretRequest": { "type": "object", "properties": { "replace_previous": { "type": "boolean", "description": "Rotate even though the secret from the last rotation still signs deliveries. That secret stops signing right\naway, receivers that only know it start rejecting deliveries.", "default": false } }, "title": "RotateWebhookSecretRequest" }, "SaveAlertRuleRequest": { "type": "object", "properties": { "metric": { "type": "string", "description": "What the rule watches.", "enum": [ "cpu_used", "cpu_iowait", "cpu_steal", "load_per_core", "memory_used", "swap_used", "disk_space_used", "inodes_used", "disk_busy", "disk_read", "disk_write", "disk_operations", "network_in", "network_out", "packets_in", "packets_out", "network_errors", "tcp_connections", "tcp_time_wait", "processes_blocked", "threads", "uptime" ], "examples": [ "disk_space_used" ] }, "condition": { "description": "Fire when the metric stays above or below the threshold.", "examples": [ "above" ], "$ref": "#\/components\/schemas\/AlertCondition" }, "threshold": { "type": "number", "description": "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.", "examples": [ 90 ], "minimum": 0, "maximum": 1000000000 }, "baseline": { "type": [ "string", "null" ], "description": "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": [ "time_of_day", null ], "default": null }, "minimum_difference": { "type": [ "number", "null" ], "description": "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.", "examples": [ 10 ], "minimum": 0, "maximum": 1000000000 }, "duration_minutes": { "type": "integer", "description": "Minutes the metric must stay above or below the threshold, 1 to 1440.", "examples": [ 10 ], "minimum": 1, "maximum": 1440 }, "scope": { "type": "string", "description": "Which of the team's servers the rule watches: all, the servers with `tag`, or the chosen `servers`.", "enum": [ "all", "tag", "servers" ], "default": "all" }, "exclude": { "type": "boolean", "description": "For tag and servers rules: watch the servers without the tag, or all servers except the chosen ones.", "default": false }, "tag": { "type": [ "string", "null" ], "description": "Formatted ID of one of the team's tags, required for tag rules.", "examples": [ "tag_01j8q8zk2f4m6n7p9r1s3t5v7x" ], "maxLength": 64 }, "servers": { "type": "array", "description": "Formatted IDs of the team's servers, required for servers rules.", "examples": [ [ "server_01j8q8zk2f4m6n7p9r1s3t5v7x" ] ], "items": { "type": "string", "maxLength": 64 }, "maxItems": 500 }, "instance": { "type": [ "string", "null" ], "description": "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.", "pattern": "^[^\\x00-\\x1F\\x7F]*$", "examples": [ "\/var" ], "maxLength": 128 }, "enabled": { "type": "boolean", "description": "Whether the rule is evaluated. Turning it off closes its open alerts.", "default": true } }, "required": [ "metric", "condition", "threshold", "duration_minutes" ], "title": "SaveAlertRuleRequest" }, "SaveServerRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable server name.", "examples": [ "web-01" ], "maxLength": 255 }, "hostname": { "type": [ "string", "null" ], "description": "Hostname of the server, or null to clear it.", "examples": [ "web-01.example.com" ], "maxLength": 255 }, "metadata": { "type": "object", "description": "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.\n\nTo remove a key, set its value to an empty string. To remove all metadata, send an empty object: `{}`.", "examples": [ { "customer": "acme", "environment": "production" } ], "additionalProperties": { "type": "string" } }, "tags": { "type": "array", "description": "Replace the server's tags with these tags of the team, by formatted ID or by name.", "examples": [ [ "production", "tag_01j8q8zk2f4m6n7p9r1s3t5v7x" ] ], "items": { "type": "string", "maxLength": 64 }, "maxItems": 50, "uniqueItems": true }, "location_override": { "type": "object", "description": "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.", "properties": { "provider": { "type": [ "string", "null" ], "description": "Provider slug, such as hetzner, aws or digitalocean.", "pattern": "^[a-z0-9][a-z0-9-]*$", "examples": [ "hetzner" ], "maxLength": 32 }, "city": { "type": [ "string", "null" ], "examples": [ "Falkenstein" ], "maxLength": 128 }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code. Without a continent override, the continent follows the country.", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW", null ], "examples": [ "DE" ] }, "continent": { "type": [ "string", "null" ], "description": "Continent code: AF, AN, AS, EU, NA, OC or SA.", "enum": [ "AF", "AN", "AS", "EU", "NA", "OC", "SA", null ], "examples": [ "EU" ] } } }, "package_metadata_refresh": { "type": "object", "description": "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.", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "True or false to set the server's own setting, null to follow the default." } } }, "agent_auto_updates": { "type": "object", "description": "Whether the agent is updated automatically when a new release has soaked. Null follows the team setting.", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "True or false to set the server's own setting, null to follow the team." } } } }, "required": [ "name" ], "title": "SaveServerRequest" }, "SaveTagRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Tag name, unique within the team. Letters, digits, spaces and . _ - : \/, starting with a letter or digit.", "pattern": "^[\\pL\\pN][\\pL\\pN _.:\\\/-]*$", "examples": [ "production" ], "maxLength": 64 }, "color": { "type": "string", "description": "Colour of the tag in the dashboard.", "enum": [ "zinc", "red", "orange", "amber", "green", "teal", "sky", "blue", "violet", "pink" ], "default": "zinc" } }, "required": [ "name" ], "title": "SaveTagRequest" }, "Server": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted server ID.", "examples": [ "server_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "web-01" ] }, "hostname": { "type": [ "string", "null" ], "description": "Hostname of the server, or null when it is not known yet.", "examples": [ "web-01.example.com" ] }, "owner_team": { "description": "The team that owns the server, installed its agent and is billed for it.", "$ref": "#\/components\/schemas\/TeamReference" }, "access": { "description": "owner for the team's own servers, viewer for a server shared with the team through a tag. Viewers cannot change the server.\n| |\n|---|\n| `owner` The team owns the server or tag: it manages it, and owns and is billed for servers. |\n| `viewer` Shared with the team through a tag: the team can view but not change it. |", "$ref": "#\/components\/schemas\/TeamAccess" }, "tags": { "type": "array", "description": "Tags of the server the team can see: all tags for the owner, the shared tags for a viewer.", "items": { "$ref": "#\/components\/schemas\/ServerTag" } }, "metadata": { "type": "object", "description": "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.", "additionalProperties": { "type": "string" } }, "status": { "description": "Agent status: pending until the agent enrolls, then active, or offline after 15 minutes without contact.\n| |\n|---|\n| `pending` Created in the dashboard, the agent has not enrolled yet. |\n| `active` The agent enrolled and reported in within the offline threshold. |\n| `offline` The agent has not reported in within the offline threshold. |", "$ref": "#\/components\/schemas\/ServerStatus" }, "agent_version": { "type": [ "string", "null" ], "description": "Version of the installed agent, or null before enrollment.", "examples": [ "1.0.0" ] }, "agent": { "type": "object", "description": "The agent and its self-updates.", "properties": { "version": { "type": [ "string", "null" ], "description": "Version of the installed agent, or null before enrollment.", "examples": [ "1.0.0" ] }, "update_available": { "type": "boolean", "description": "Whether a newer stable agent release than the installed version exists." }, "auto_updates": { "type": "object", "description": "Whether the agent is updated automatically when a release has soaked for 24 hours.", "properties": { "enabled": { "type": "boolean", "description": "Whether the agent is updated automatically, the server's own setting or the team's." }, "is_default": { "type": "boolean", "description": "True when the server follows the team setting, false when the owner set it for this server." } }, "required": [ "enabled", "is_default" ] }, "capability": { "type": "object", "description": "Whether the agent can update itself, as it reported in its last heartbeat.", "properties": { "available": { "type": "boolean", "description": "True when the agent was installed from the Server Chief package repository and can run its update helper." }, "reason": { "type": [ "string", "null" ], "description": "Why the agent cannot update itself, null when it can.", "examples": [ "installed from a tarball" ] } }, "required": [ "available", "reason" ] }, "reboot": { "type": "object", "description": "Whether the agent can reboot the server, as it reported in its last heartbeat.", "properties": { "available": { "type": "boolean", "description": "True when the agent can reboot the server and its operator did not turn reboots off." }, "reason": { "type": [ "string", "null" ], "description": "Why the agent cannot reboot the server, null when it can.", "examples": [ "running in a Docker container" ] } }, "required": [ "available", "reason" ] }, "upgrade_packages": { "type": "object", "description": "Whether the agent can install package updates, as it reported in its last heartbeat.", "properties": { "available": { "type": "boolean", "description": "True when the agent can install package updates and its operator did not turn it off." }, "reason": { "type": [ "string", "null" ], "description": "Why the agent cannot install package updates, null when it can.", "examples": [ "the root helper does not answer" ] } }, "required": [ "available", "reason" ] }, "disabled_actions": { "type": "array", "description": "Remote actions the server's operator turned off on the server with `serverchief disable`, which only they can turn on again.", "items": { "$ref": "#\/components\/schemas\/RemoteAction" } } }, "required": [ "version", "update_available", "auto_updates", "capability", "reboot", "upgrade_packages", "disabled_actions" ] }, "last_contact_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the last agent contact, or null when the agent never reported in." }, "fqdn": { "type": [ "string", "null" ], "description": "Fully qualified domain name reported by the server.", "examples": [ "web-01.example.com" ] }, "os_family": { "type": [ "string", "null" ], "description": "Operating system family.", "examples": [ "debian" ] }, "os_id": { "type": [ "string", "null" ], "description": "Operating system ID from os-release.", "examples": [ "ubuntu" ] }, "os_name": { "type": [ "string", "null" ], "examples": [ "Ubuntu" ] }, "os_version": { "type": [ "string", "null" ], "description": "Full operating system version.", "examples": [ "24.04.1" ] }, "os_codename": { "type": [ "string", "null" ], "examples": [ "noble" ] }, "kernel_release": { "type": [ "string", "null" ], "examples": [ "6.8.0-45-generic" ] }, "arch": { "type": [ "string", "null" ], "description": "CPU architecture.", "examples": [ "amd64" ] }, "virtualization": { "type": [ "string", "null" ], "description": "Virtualization role and technology, or null on bare metal.", "examples": [ "guest\/kvm" ] }, "boot_time": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the last boot." }, "cpu_model": { "type": [ "string", "null" ], "examples": [ "AMD EPYC 7763 64-Core Processor" ] }, "cpu_cores": { "type": [ "integer", "null" ], "description": "Physical CPU cores, or logical CPUs when the core count is unknown.", "examples": [ 4 ] }, "cpu_threads": { "type": [ "integer", "null" ], "description": "Logical CPUs.", "examples": [ 8 ] }, "memory_bytes": { "type": [ "integer", "null" ], "description": "Total memory in bytes.", "examples": [ 17179869184 ] }, "swap_bytes": { "type": [ "integer", "null" ], "description": "Total swap in bytes." }, "disk_bytes": { "type": [ "integer", "null" ], "description": "Combined size of the non-removable physical disks in bytes, without RAID arrays, ZFS volumes and other devices built on them." }, "storage_health": { "anyOf": [ { "description": "Health of the software RAID arrays, ZFS pools and disks: degraded when 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; failed when an array or pool stopped, files have permanent errors, or a disk outside any array or pool failed. Null until the agent reports it.\n| |\n|---|\n| `healthy` Every array and pool has all its devices without errors and every disk works. |\n| `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. |\n| `failed` An array or pool stopped, files have permanent errors, or a disk outside any array or pool failed: data is unavailable. |", "$ref": "#\/components\/schemas\/StorageHealth" }, { "type": "null" } ] }, "storage_unhealthy_since": { "type": [ "string", "null" ], "description": "When the storage stopped being healthy, null while it is healthy." }, "public_ipv4": { "type": [ "string", "null" ], "description": "Primary public IPv4 address.", "examples": [ "203.0.113.10" ] }, "public_ipv6": { "type": [ "string", "null" ], "description": "Primary public IPv6 address.", "examples": [ "2001:db8::10" ] }, "observed_ip": { "type": [ "string", "null" ], "description": "The address the agent's requests come from, used to locate servers behind NAT.", "examples": [ "198.51.100.7" ] }, "nameservers": { "type": [ "array", "null" ], "description": "Configured DNS resolvers, or null when not reported yet.", "items": { "type": "string" } }, "addresses": { "type": "array", "description": "IP addresses on the server's network interfaces.", "items": { "$ref": "#\/components\/schemas\/ServerAddress" } }, "is_os_eol": { "type": "boolean", "description": "Whether the operating system release is past its end of life according to endoflife.date." }, "os_eol_at": { "type": [ "string", "null" ], "description": "End-of-life date of the operating system release, or null when unknown." }, "pending_updates_count": { "type": [ "integer", "null" ], "description": "Number of packages with a pending update, or null before the agent reported updates.", "examples": [ 12 ] }, "security_updates_count": { "type": [ "integer", "null" ], "description": "Number of pending security updates, or null before the agent reported updates.", "examples": [ 3 ] }, "reboot_required": { "type": [ "boolean", "null" ], "description": "Whether the server needs a reboot, null when the agent cannot tell." }, "updates_checked_at": { "type": [ "string", "null" ], "description": "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." }, "package_metadata_refresh": { "type": "object", "description": "Whether the agent refreshes the package lists itself (apt-get update, yum or dnf makecache). It never installs, upgrades or removes packages.", "properties": { "enabled": { "type": "boolean", "description": "Whether the agent refreshes the package lists, the server's own setting or the default." }, "interval": { "type": "integer", "description": "Seconds between refreshes.", "examples": [ 21600 ] }, "is_default": { "type": "boolean", "description": "True when the server follows the default, false when the owner set it for this server." } }, "required": [ "enabled", "interval", "is_default" ] }, "software": { "type": "array", "description": "Software products detected from the installed packages, one entry per product and major.minor.", "items": { "$ref": "#\/components\/schemas\/ServerSoftware" } }, "provider": { "type": [ "string", "null" ], "description": "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.", "examples": [ "hetzner" ] }, "city": { "type": [ "string", "null" ], "description": "City derived from the provider region or set manually, IP lookups give no city.", "examples": [ "Falkenstein" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code.", "examples": [ "DE" ] }, "continent": { "type": [ "string", "null" ], "description": "Continent code: AF, AN, AS, EU, NA, OC or SA.", "examples": [ "EU" ] }, "location_source": { "anyOf": [ { "description": "Where the location came from: agent for cloud metadata, ip for an IP lookup, manual when the owner overrode a field. Null when unknown.\n| |\n|---|\n| `agent` Reported by the agent from cloud metadata or DMI, mapped from the provider region. |\n| `ip` Looked up from the server's public or observed IP address in the IPInfo database: provider and country, no city. |\n| `manual` Set by the owner team, it wins over agent and IP data. |", "$ref": "#\/components\/schemas\/ServerLocationSource" }, { "type": "null" } ] }, "cloud_region": { "type": [ "string", "null" ], "description": "Provider region as reported by the agent, such as fsn1 or eu-central-1.", "examples": [ "fsn1" ] }, "cloud_zone": { "type": [ "string", "null" ], "description": "Provider zone as reported by the agent.", "examples": [ "fsn1-dc14" ] }, "instance_type": { "type": [ "string", "null" ], "description": "Instance type, null where the provider does not expose it.", "examples": [ "m6i.large" ] }, "asn": { "type": [ "integer", "null" ], "description": "Autonomous system number of the server's IP address.", "examples": [ 24940 ] }, "asn_org": { "type": [ "string", "null" ], "description": "Name of the autonomous system.", "examples": [ "Hetzner Online GmbH" ] }, "location_override": { "type": "object", "description": "Location fields the owner set manually, they win over detected values. Null fields use the detected value.", "properties": { "provider": { "type": [ "string", "null" ], "examples": [ "hetzner" ] }, "city": { "type": [ "string", "null" ], "examples": [ "Falkenstein" ] }, "country": { "type": [ "string", "null" ], "examples": [ "DE" ] }, "continent": { "type": [ "string", "null" ], "examples": [ "EU" ] } }, "required": [ "provider", "city", "country", "continent" ] }, "vhosts_count": { "type": [ "integer", "null" ], "description": "Number of sites (virtual hosts) on the server, or null before the agent reported them.", "examples": [ 12 ] }, "certificates_count": { "type": [ "integer", "null" ], "description": "Certificates of the server's sites and services, null before the agent reported them.", "examples": [ 4 ] }, "certificate_issues_count": { "type": [ "integer", "null" ], "description": "Certificates failing at least one check, null before the agent reported certificates.", "examples": [ 1 ] }, "repositories": { "type": [ "object", "null" ], "description": "Package repositories and where the installed packages come from, null before the agent reported repositories.", "properties": { "count": { "type": "integer", "description": "Configured repositories, enabled or not.", "examples": [ 8 ] }, "third_party_count": { "type": "integer", "description": "Enabled repositories outside the distribution.", "examples": [ 3 ] }, "issues_count": { "type": "integer", "description": "Enabled repositories with an issue that is not informational: no signature check or plain HTTP.", "examples": [ 1 ] }, "orphaned_packages_count": { "type": [ "integer", "null" ], "description": "Installed packages no configured repository offers, null without package origins.", "examples": [ 2 ] }, "not_covered_packages_count": { "type": [ "integer", "null" ], "description": "Installed packages only third-party repositories offer. Distribution advisories are not matched against them, so vulnerabilities does not cover them. Null without package origins.", "examples": [ 4 ] }, "vendors": { "type": "array", "description": "The vendors of the enabled repositories, third parties first, with the issues of their repositories.", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "label": { "type": "string" }, "kind": { "$ref": "#\/components\/schemas\/RepositoryVendorKind" }, "repositories": { "type": "integer" }, "issues": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RepositoryIssue" } } }, "required": [ "slug", "label", "kind", "repositories", "issues" ] } } }, "required": [ "count", "third_party_count", "issues_count", "orphaned_packages_count", "not_covered_packages_count", "vendors" ] }, "vulnerabilities": { "type": [ "object", "null" ], "description": "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.", "properties": { "release": { "type": [ "string", "null" ], "description": "The advisory release the server's packages are matched against.", "examples": [ "debian:12" ] }, "critical": { "type": "integer", "examples": [ 2 ] }, "high": { "type": "integer", "examples": [ 5 ] }, "medium": { "type": "integer", "examples": [ 12 ] }, "low": { "type": "integer", "examples": [ 20 ] }, "negligible": { "type": "integer", "examples": [ 30 ] }, "unknown": { "type": "integer", "examples": [ 1 ] }, "total": { "type": "integer", "examples": [ 70 ] }, "fixable": { "type": "integer", "description": "Vulnerabilities a pending update fixes for every affected package. `fixable`, `reboot`, `subscription`, `released` and `unfixed` add up to `total`: each counts for the least actionable fix of its packages.", "examples": [ 9 ] }, "reboot": { "type": "integer", "description": "Vulnerabilities fixed by rebooting into a kernel that is already installed.", "examples": [ 1 ] }, "subscription": { "type": "integer", "description": "Vulnerabilities with an Ubuntu Pro (ESM) fix the server does not get without a subscription.", "examples": [ 3 ] }, "released": { "type": "integer", "description": "Vulnerabilities with a released fix the package manager does not offer yet, for example because its package lists are old.", "examples": [ 0 ] }, "unfixed": { "type": "integer", "description": "Vulnerabilities without a fix from the distribution yet.", "examples": [ 57 ] }, "checked_at": { "type": "string", "description": "ISO 8601 timestamp the packages were last matched." } }, "required": [ "release", "critical", "high", "medium", "low", "negligible", "unknown", "total", "fixable", "reboot", "subscription", "released", "unfixed", "checked_at" ] }, "enrollment": { "anyOf": [ { "description": "The one-time enrollment token, only returned when creating a server or issuing a token, null otherwise.", "$ref": "#\/components\/schemas\/ServerEnrollment" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "name", "hostname", "owner_team", "access", "tags", "metadata", "status", "agent_version", "agent", "last_contact_at", "fqdn", "os_family", "os_id", "os_name", "os_version", "os_codename", "kernel_release", "arch", "virtualization", "boot_time", "cpu_model", "cpu_cores", "cpu_threads", "memory_bytes", "swap_bytes", "disk_bytes", "storage_health", "storage_unhealthy_since", "public_ipv4", "public_ipv6", "observed_ip", "nameservers", "addresses", "is_os_eol", "os_eol_at", "pending_updates_count", "security_updates_count", "reboot_required", "updates_checked_at", "package_metadata_refresh", "software", "provider", "city", "country", "continent", "location_source", "cloud_region", "cloud_zone", "instance_type", "asn", "asn_org", "location_override", "vhosts_count", "certificates_count", "certificate_issues_count", "repositories", "vulnerabilities", "enrollment", "created_at", "updated_at" ], "title": "Server" }, "ServerAddress": { "type": "object", "properties": { "interface": { "type": "string", "description": "Name of the network interface.", "examples": [ "eth0" ] }, "address": { "type": "string", "examples": [ "203.0.113.10" ] }, "prefix": { "type": "integer", "description": "Prefix length of the network.", "examples": [ 24 ] }, "family": { "type": "integer", "description": "IP version, 4 or 6.", "examples": [ 4 ] }, "scope": { "type": "string", "description": "Scope of the address as classified by the agent, such as public, private, link-local or loopback.", "examples": [ "public" ] } }, "required": [ "interface", "address", "prefix", "family", "scope" ], "title": "ServerAddress" }, "ServerCertificate": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted certificate ID.", "examples": [ "certificate_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "server": { "type": "object", "description": "The server using the certificate.", "properties": { "id": { "type": "string", "description": "Formatted server ID.", "examples": [ "server_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "web-01" ] } }, "required": [ "id", "name" ] }, "fingerprint": { "type": "string", "description": "SHA-256 of the leaf certificate's DER encoding, lowercase hex. Sites link to it by the fingerprint of their certificate.", "examples": [ "3f6c1a9e0b7d4c2a8e5f1b3d7a9c0e2f4b6d8a1c3e5f7b9d0a2c4e6f8b1d3a5c" ] }, "serial": { "type": [ "string", "null" ], "description": "Serial number, hex.", "examples": [ "04a1b2c3d4e5f60718293a4b5c6d7e8f9a0b" ] }, "subject": { "type": "object", "description": "The subject's common name and organisation.", "properties": { "cn": { "type": [ "string", "null" ], "examples": [ "shop.example.com" ] }, "org": { "type": [ "string", "null" ] } }, "required": [ "cn", "org" ] }, "issuer": { "type": "object", "description": "The issuer's common name and organisation.", "properties": { "cn": { "type": [ "string", "null" ], "examples": [ "R11" ] }, "org": { "type": [ "string", "null" ], "examples": [ "Let's Encrypt" ] } }, "required": [ "cn", "org" ] }, "not_before": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp the certificate is valid from." }, "not_after": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp the certificate expires at." }, "expired": { "type": "boolean", "description": "Whether the certificate has expired." }, "days_left": { "type": [ "integer", "null" ], "description": "Whole days until the certificate expires, negative once it expired, null without an expiry.", "examples": [ 42 ] }, "names": { "type": "array", "description": "DNS names and IP addresses the certificate covers, sorted and in lower case.", "examples": [ [ "shop.example.com", "www.shop.example.com" ] ], "items": { "type": "string" } }, "key": { "type": "object", "description": "The public key.", "properties": { "type": { "type": [ "string", "null" ], "description": "rsa, ecdsa or ed25519. New values may be added.", "examples": [ "ecdsa" ] }, "bits": { "type": [ "integer", "null" ], "examples": [ 256 ] }, "curve": { "type": [ "string", "null" ], "description": "The EC curve, null for other key types.", "examples": [ "P-256" ] } }, "required": [ "type", "bits", "curve" ] }, "signature_algorithm": { "type": [ "string", "null" ], "examples": [ "ECDSA-SHA384" ] }, "self_signed": { "type": "boolean", "description": "Whether the certificate is self-signed." }, "chain": { "type": "object", "description": "The intermediate chain found next to the certificate.", "properties": { "complete": { "type": [ "boolean", "null" ], "description": "Whether the certificate verifies to a trusted root with these intermediates, null when it could not be determined." }, "intermediates": { "type": [ "integer", "null" ], "examples": [ 1 ] } }, "required": [ "complete", "intermediates" ] }, "paths": { "type": "array", "description": "Certificate files the certificate was found in, sorted.", "examples": [ [ "\/etc\/letsencrypt\/live\/shop.example.com\/fullchain.pem" ] ], "items": { "type": "string" } }, "used_by": { "type": "array", "description": "Sites and services configured with the certificate.", "items": { "$ref": "#\/components\/schemas\/CertificateUsedBy" } }, "managed_by": { "type": "object", "description": "The tool that issued the certificate and renews it. Its fields are null when no tool was detected.", "properties": { "tool": { "anyOf": [ { "description": "certbot, acme.sh, plesk or directadmin, null when none was detected.", "$ref": "#\/components\/schemas\/CertificateManager" }, { "type": "null" } ] }, "name": { "type": [ "string", "null" ], "description": "The certbot lineage, acme.sh domain or panel certificate name.", "examples": [ "shop.example.com" ] }, "plugin": { "type": [ "string", "null" ], "description": "The authenticator: webroot, nginx, apache, standalone, dns-cloudflare, dns-domainchief, acme.sh dns_cf and so on. New values may be added.", "examples": [ "dns-domainchief" ] }, "installer": { "type": [ "string", "null" ], "examples": [ "apache" ] }, "ca": { "type": [ "string", "null" ], "description": "Normalised CA: letsencrypt, letsencrypt-staging, zerossl, buypass, google or sectigo. New values may be added.", "examples": [ "letsencrypt" ] }, "ca_url": { "type": [ "string", "null" ], "examples": [ "https:\/\/acme-v02.api.letsencrypt.org\/directory" ] }, "renewal": { "anyOf": [ { "description": "The renewal automation found, null when the agent could not tell.\n| |\n|---|\n| `timer` A systemd timer, such as certbot.timer. |\n| `cron` A cron job, such as `certbot renew` or `acme.sh --cron`. |\n| `panel` The hosting panel renews it. |\n| `none` No renewal automation was found. |", "$ref": "#\/components\/schemas\/CertificateRenewal" }, { "type": "null" } ] }, "config": { "type": [ "string", "null" ], "description": "The renewal configuration file.", "examples": [ "\/etc\/letsencrypt\/renewal\/shop.example.com.conf" ] } }, "required": [ "tool", "name", "plugin", "installer", "ca", "ca_url", "renewal", "config" ] }, "issues": { "type": "array", "description": "The checks the certificate fails, the most severe first.", "items": { "$ref": "#\/components\/schemas\/CertificateIssueDetails" } }, "severity": { "anyOf": [ { "description": "The most severe issue's severity, null without issues.\n| |\n|---|\n| `high` Visitors or mail clients get errors now or soon: an expiring certificate nobody renews, an untrusted CA. |\n| `medium` Some clients fail or the certificate is weaker than it should be. |\n| `low` Housekeeping, nothing breaks. |", "$ref": "#\/components\/schemas\/CertificateIssueSeverity" }, { "type": "null" } ] }, "first_seen_at": { "type": "string", "description": "ISO 8601 timestamp the certificate was first reported on the server." }, "url": { "type": "string", "description": "The certificate's page in Server Chief.", "examples": [ "https:\/\/server.chief.app\/team\/acme\/certificates\/01j8q8zk2f4m6n7p9r1s3t5v7x" ] } }, "required": [ "id", "fingerprint", "serial", "subject", "issuer", "not_before", "not_after", "expired", "days_left", "names", "key", "signature_algorithm", "self_signed", "chain", "paths", "used_by", "managed_by", "issues", "severity", "first_seen_at", "url" ], "title": "ServerCertificate" }, "ServerChange": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted change ID.", "examples": [ "change_01jb9a2c3d4e5f6g7h8j9k0m1n" ] }, "dataset": { "type": "string", "description": "Dataset the change belongs to: an inventory dataset, vulnerabilities or agent. New values may be added.", "examples": [ "packages" ] }, "kind": { "$ref": "#\/components\/schemas\/ServerChangeKind" }, "subject": { "type": "string", "description": "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.", "examples": [ "php8.2-fpm" ] }, "label": { "type": "string", "description": "Readable description of the subject.", "examples": [ "Package php8.2-fpm" ] }, "old": { "description": "Value before the change, null when added. Its shape depends on the dataset and subject." }, "new": { "description": "Value after the change, null when removed. Its shape depends on the dataset and subject." }, "detected_at": { "type": "string", "description": "ISO 8601 timestamp the change was detected." } }, "required": [ "id", "dataset", "kind", "subject", "label", "old", "new", "detected_at" ], "title": "ServerChange" }, "ServerChangeKind": { "type": "string", "description": "| |\n|---|\n| `changed` A value was replaced, both old and new are set. |\n| `added` An item appeared, only new is set. |\n| `removed` An item disappeared, only old is set. |", "x-extensible-enum": [ "changed", "added", "removed" ], "title": "ServerChangeKind" }, "ServerCommand": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted command ID.", "examples": [ "command_01jb9a2c3d4e5f6g7h8j9k0m1n" ] }, "kind": { "$ref": "#\/components\/schemas\/ServerCommandKind" }, "status": { "description": "Agent status of the command.\n| |\n|---|\n| `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. |\n| `pending` Waiting for the agent to fetch it. |\n| `delivered` Returned to the agent, not acknowledged yet. |\n| `acknowledged` The agent accepted the command and is working on it. |\n| `succeeded` The agent finished the command successfully. |\n| `failed` The agent reported that the command failed. |\n| `cancelled` Someone cancelled it before the agent fetched it. |\n| `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). |", "$ref": "#\/components\/schemas\/ServerCommandStatus" }, "datasets": { "type": [ "array", "null" ], "description": "Datasets the command applies to, or null for every enabled dataset.", "items": { "type": "string" } }, "version": { "type": [ "string", "null" ], "description": "Agent version an update_agent command installs, null for other kinds.", "examples": [ "1.2.3" ] }, "detail": { "type": [ "string", "null" ], "description": "Result detail reported by the agent." }, "update_result": { "type": [ "object", "null" ], "description": "Outcome of an update_agent command, null for other kinds and before the agent reported a result.", "properties": { "code": { "anyOf": [ { "description": "Result code, null when the agent reported a code this API does not know yet. An update that expired after the agent acknowledged it is install_failed.\n| |\n|---|\n| `updated` The target version is installed and running. |\n| `install_failed` The package manager failed, the previous version is still installed. |\n| `readiness_failed_rolled_back` The new version did not become ready, the previous version was reinstalled and runs again. |\n| `rollback_failed` The new version did not become ready and reinstalling the previous version failed too. |\n| `target_unavailable` The package repository does not offer the target version. |\n| `rollback_unavailable` The package repository does not offer the installed version, which a rollback needs, so the update was not attempted. |\n| `package_manager_busy` Another process held the package manager lock for an hour. |\n| `unsupported_install` The agent was not installed from the Server Chief package and repository. |", "$ref": "#\/components\/schemas\/AgentUpdateResult" }, { "type": "null" } ] }, "previous_version": { "type": [ "string", "null" ], "description": "Agent version before the update.", "examples": [ "1.2.2" ] }, "target_version": { "type": [ "string", "null" ], "description": "Agent version the update installed.", "examples": [ "1.2.3" ] }, "installed_version": { "type": [ "string", "null" ], "description": "Agent version installed after the update, or after the rollback.", "examples": [ "1.2.3" ] } }, "required": [ "code", "previous_version", "target_version", "installed_version" ] }, "reboot_result": { "type": [ "object", "null" ], "description": "Outcome of a reboot command, null for other kinds and before the agent reported a result.", "properties": { "code": { "anyOf": [ { "description": "Result code, null when the agent reported a code this API does not know yet.\n| |\n|---|\n| `rebooted` The server rebooted and the agent started again. |\n| `disabled` The server's operator turned reboots off with `serverchief disable reboot`. |\n| `unsupported` The agent cannot reboot this server, the detail says why. |\n| `package_manager_busy` A package manager held its lock for 15 minutes, the server was not rebooted. |\n| `reboot_failed` Scheduling the reboot failed, the output shows why. |\n| `not_rebooted` The reboot was scheduled but the server did not reboot within 10 minutes, someone may have cancelled it. |\n| `too_late` The reboot was not started before its `not_after` deadline, such as the end of a maintenance window. |\n| `not_required` A reboot only when required found the server did not need one, so it did not reboot. |\n| `required_unknown` A reboot only when required could not tell whether the server needs one, so it did not reboot. |", "$ref": "#\/components\/schemas\/RebootResult" }, { "type": "null" } ] }, "previous_boot_time": { "type": [ "string", "null" ], "description": "ISO 8601 boot time before the reboot, null when unknown." }, "boot_time": { "type": [ "string", "null" ], "description": "ISO 8601 boot time after the reboot, or when the reboot did not happen, null when unknown." } }, "required": [ "code", "previous_boot_time", "boot_time" ] }, "upgrade_result": { "type": [ "object", "null" ], "description": "Outcome of an upgrade_packages command, null for other kinds and before the agent reported a result.", "properties": { "code": { "anyOf": [ { "description": "Result code, null when the agent reported a code this API does not know yet.\n| |\n|---|\n| `upgraded` The updates of the scope were installed. |\n| `nothing_to_upgrade` No update of the scope was pending. |\n| `upgrade_failed` The package manager failed, the output shows why. Some updates may have been installed. |\n| `dpkg_interrupted` dpkg reports an interrupted install, which someone has to finish with `dpkg --configure -a` first. |\n| `security_unavailable` The repositories have no security metadata, so security updates cannot be told apart. |\n| `package_manager_busy` A package manager held its lock for an hour. |\n| `too_late` The updates were not started before the `not_after` deadline, such as the end of a maintenance window. |\n| `disabled` The server's operator turned installing updates off with `serverchief disable upgrade_packages`. |\n| `unsupported` The agent cannot install updates on this server, the detail says why. |", "$ref": "#\/components\/schemas\/PackageUpgradeResult" }, { "type": "null" } ] }, "scope": { "anyOf": [ { "description": "Which updates were installed.\n| |\n|---|\n| `security` The pending updates the agent marks as security updates. |\n| `all` Every pending update. |", "$ref": "#\/components\/schemas\/PackageUpgradeScope" }, { "type": "null" } ] }, "upgraded": { "type": [ "integer", "null" ], "description": "How many packages were upgraded, null when unknown." }, "held_back": { "type": [ "integer", "null" ], "description": "How many pending updates of the scope were left, such as phased updates, null when unknown." }, "reboot_required": { "type": [ "boolean", "null" ], "description": "Whether a reboot is required afterwards, null when unknown." }, "services_restarted": { "type": [ "array", "null" ], "description": "The services that were restarted, null when services were not restarted or it cannot be told.", "items": { "type": "string" } }, "agent_update": { "type": [ "object", "null" ], "description": "The agent's own update before the package updates, null when the agent was not updated.", "properties": { "code": { "type": [ "string", "null" ] }, "previous_version": { "type": [ "string", "null" ] }, "installed_version": { "type": [ "string", "null" ] } }, "required": [ "code", "previous_version", "installed_version" ] } }, "required": [ "code", "scope", "upgraded", "held_back", "reboot_required", "services_restarted", "agent_update" ] }, "origin": { "anyOf": [ { "description": "Where the command came from: the web app, the API (including MCP) or Server Chief itself, null for commands from before it was recorded.\n| |\n|---|\n| `panel` Someone asked for it in the web app. |\n| `api` An API or MCP client asked for it. |\n| `system` Server Chief queued it on its own, such as the automatic agent rollout. |", "$ref": "#\/components\/schemas\/ServerCommandOrigin" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "expires_at": { "type": "string", "description": "ISO 8601 timestamp after which an unacknowledged command expires." }, "finished_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the agent's result, or null while the command is outstanding." } }, "required": [ "id", "kind", "status", "datasets", "version", "detail", "update_result", "reboot_result", "upgrade_result", "origin", "created_at", "expires_at", "finished_at" ], "title": "ServerCommand" }, "ServerCommandKind": { "type": "string", "description": "| |\n|---|\n| `refresh_inventory` Collect the listed datasets, or all enabled ones, now and push whatever changed. |\n| `resync` Send the listed datasets, or all enabled ones, in full on the next push. |\n| `refresh_config` Fetch the agent configuration now. |\n| `update_agent` Install another agent version from the Server Chief package repository, with a rollback when it does not start. |\n| `reboot` Reboot the server in one minute, after waiting for the package manager, unless its operator turned reboots off. |\n| `upgrade_packages` Install the pending package updates, the agent's own package first, unless the operator turned this off. |\n| `disable_capability` Turn a remote action off on the server, only `serverchief enable` on the server turns it on again. |", "x-extensible-enum": [ "refresh_inventory", "resync", "refresh_config", "update_agent", "reboot", "upgrade_packages", "disable_capability" ], "title": "ServerCommandKind" }, "ServerCommandOrigin": { "type": "string", "description": "Where a command came from, recorded with the user who asked for it.\n| |\n|---|\n| `panel` Someone asked for it in the web app. |\n| `api` An API or MCP client asked for it. |\n| `system` Server Chief queued it on its own, such as the automatic agent rollout. |", "x-extensible-enum": [ "panel", "api", "system" ], "title": "ServerCommandOrigin" }, "ServerCommandStatus": { "type": "string", "description": "| |\n|---|\n| `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. |\n| `pending` Waiting for the agent to fetch it. |\n| `delivered` Returned to the agent, not acknowledged yet. |\n| `acknowledged` The agent accepted the command and is working on it. |\n| `succeeded` The agent finished the command successfully. |\n| `failed` The agent reported that the command failed. |\n| `cancelled` Someone cancelled it before the agent fetched it. |\n| `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). |", "x-extensible-enum": [ "queued", "pending", "delivered", "acknowledged", "succeeded", "failed", "cancelled", "expired" ], "title": "ServerCommandStatus" }, "ServerCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A server was added and waits for its agent.", "enum": [ "server.created" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Server" } }, "required": [ "object" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "ServerCreatedEvent" }, "ServerDeletedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A server was removed.", "enum": [ "server.deleted" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Server" } }, "required": [ "object" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "ServerDeletedEvent" }, "ServerEnrolledEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A server's agent enrolled for the first time.", "enum": [ "server.enrolled" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Server" } }, "required": [ "object" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "ServerEnrolledEvent" }, "ServerEnrollment": { "type": "object", "properties": { "token": { "type": "string", "description": "One-time enrollment token. It is only returned once, store it or run the install command right away.", "examples": [ "scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE" ] }, "install_command": { "type": "string", "description": "Shell command that installs the agent and enrolls it with the token, run it as root on the server.", "examples": [ "curl -fsSL https:\/\/pkg.server.chief.app\/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE" ] }, "expires_at": { "type": "string", "description": "ISO 8601 timestamp after which the token can no longer be used." } }, "required": [ "token", "install_command", "expires_at" ], "title": "ServerEnrollment" }, "ServerInventory": { "type": "object", "properties": { "dataset": { "$ref": "#\/components\/schemas\/InventoryDataset" }, "collected": { "type": "boolean", "description": "Whether the agent collects the dataset, false when the team or server turned it off." }, "received_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the agent's last report of the dataset, null before the first." }, "payload": { "type": [ "object", "null" ], "description": "The dataset as the agent reported it, see the agent protocol for its fields. Null before the first report.", "additionalProperties": {} } }, "required": [ "dataset", "collected", "received_at", "payload" ], "title": "ServerInventory" }, "ServerLocationSource": { "type": "string", "description": "| |\n|---|\n| `agent` Reported by the agent from cloud metadata or DMI, mapped from the provider region. |\n| `ip` Looked up from the server's public or observed IP address in the IPInfo database: provider and country, no city. |\n| `manual` Set by the owner team, it wins over agent and IP data. |", "x-extensible-enum": [ "agent", "ip", "manual" ], "title": "ServerLocationSource" }, "ServerMetricSeries": { "type": "object", "properties": { "range": { "type": "string", "examples": [ "6h" ] }, "collecting": { "type": "boolean", "description": "Whether the server collects metrics: its agent sends them and the owner did not turn them off." }, "since": { "type": [ "string", "null" ], "description": "ISO 8601 time of the oldest kept sample: a range reaching further back has no buckets before it." }, "series": { "type": "array", "description": "One series per metric and instance, sorted by metric and instance.", "items": { "$ref": "#\/components\/schemas\/MetricSeries" } } }, "required": [ "range", "collecting", "since", "series" ], "title": "ServerMetricSeries" }, "ServerMetrics": { "type": "object", "properties": { "collecting": { "type": "boolean", "description": "Whether the server collects metrics: its agent sends them and the owner did not turn them off." }, "since": { "type": [ "string", "null" ], "description": "ISO 8601 time of the oldest kept sample, or when collection started while there is none yet." }, "values": { "type": "array", "description": "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.", "items": { "$ref": "#\/components\/schemas\/MetricValue" } } }, "required": [ "collecting", "since", "values" ], "title": "ServerMetrics" }, "ServerOfflineEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A server stopped checking in.", "enum": [ "server.offline" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Server" } }, "required": [ "object" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "ServerOfflineEvent" }, "ServerOnlineEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "An offline server checks in again.", "enum": [ "server.online" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Server" }, "offline_since": { "type": "string", "format": "date-time", "description": "When the server went offline." } }, "required": [ "object", "offline_since" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "ServerOnlineEvent" }, "ServerPackage": { "type": "object", "properties": { "server": { "type": "object", "description": "The server the package is installed on, only included when searching packages across servers.", "properties": { "id": { "type": "string", "description": "Formatted server ID.", "examples": [ "server_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "web-01" ] } }, "required": [ "id", "name" ] }, "manager": { "type": "string", "description": "Package manager, dpkg or rpm.", "examples": [ "dpkg" ] }, "name": { "type": "string", "examples": [ "openssl" ] }, "arch": { "type": "string", "examples": [ "amd64" ] }, "version": { "type": "string", "description": "Installed version as reported by the package manager, including epoch and revision. Version filters compare it like dpkg or rpm.", "examples": [ "1.0.2g-1ubuntu4.20" ] }, "upstream_version": { "type": "string", "description": "Upstream part of the version, without epoch and revision.", "examples": [ "1.0.2g" ] }, "source": { "type": [ "string", "null" ], "description": "Source package, when it differs from the package name.", "examples": [ "util-linux" ] }, "source_version": { "type": [ "string", "null" ], "description": "Version of the source package, when it differs from the version. Security advisories compare it.", "examples": [ "2.36-9+deb12u4" ] }, "candidate_version": { "type": [ "string", "null" ], "description": "Version an update would install, or null when the package is up to date.", "examples": [ "1.0.2g-1ubuntu4.21" ] }, "is_security": { "type": "boolean", "description": "Whether the pending update is a security update." }, "origins": { "type": [ "array", "null" ], "description": "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.", "examples": [ [ "bookworm:c4a17d93" ] ], "items": { "type": "string" } }, "origin_vendor": { "type": [ "string", "null" ], "description": "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.", "examples": [ "sury" ] }, "origin_kind": { "description": "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).\n| |\n|---|\n| `distro` A distribution repository offers the installed version, security advisories cover it. |\n| `third_party` Only third-party repositories offer it, distribution advisories do not cover it. |\n| `none` No configured repository offers it: a manually installed package, a removed repository or a superseded version. |\n| `unknown` The agent could not tell, or the repositories are not known yet. |", "$ref": "#\/components\/schemas\/PackageOriginKind" } }, "required": [ "manager", "name", "arch", "version", "upstream_version", "source", "source_version", "candidate_version", "is_security", "origins", "origin_vendor", "origin_kind" ], "title": "ServerPackage" }, "ServerRebootStalledEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A server did not come back after a reboot.", "enum": [ "server.reboot_stalled" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Server" }, "command_id": { "type": "string", "description": "The ID of the reboot command the server did not come back from." } }, "required": [ "object", "command_id" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "ServerRebootStalledEvent" }, "ServerRepository": { "type": "object", "properties": { "id": { "type": "string", "description": "The repository ID the agent reports, as listed in package origins: a suite-prefixed hash for apt, the section name for rpm.", "examples": [ "bookworm-security:3f2a9c1e" ] }, "file": { "type": [ "string", "null" ], "description": "The file defining it.", "examples": [ "\/etc\/apt\/sources.list.d\/php.list" ] }, "type": { "type": "string", "description": "deb, deb-src or rpm.", "examples": [ "deb" ] }, "enabled": { "type": "boolean", "description": "Whether the package manager uses it. Disabled repositories have no issues." }, "uris": { "type": "array", "description": "The configured URIs without credentials or query strings, mirror lists prefixed with mirrorlist: or metalink: and keeping their identifying parameters such as repo.", "examples": [ [ "https:\/\/packages.sury.org\/php" ] ], "items": { "type": "string" } }, "suite": { "type": [ "string", "null" ], "description": "The apt suite, null for rpm.", "examples": [ "bookworm" ] }, "components": { "type": "array", "description": "The apt components, empty for rpm.", "examples": [ [ "main" ] ], "items": { "type": "string" } }, "name": { "type": [ "string", "null" ], "description": "The rpm repository name, null for apt.", "examples": [ "Remi's PHP 8.3 RPM repository for Enterprise Linux 9" ] }, "signing": { "type": "object", "description": "How the package manager verifies it.", "properties": { "signed_by": { "type": [ "string", "null" ], "description": "The keyring path or key fingerprint from signed-by, null when apt falls back to the global keyring.", "examples": [ "\/usr\/share\/keyrings\/deb.sury.org-php.gpg" ] }, "trusted": { "type": "boolean", "description": "apt trusted=yes: signatures are not checked." }, "gpgcheck": { "type": [ "boolean", "null" ], "description": "rpm gpgcheck, null for apt or when not set." } }, "required": [ "signed_by", "trusted", "gpgcheck" ] }, "transport": { "type": [ "string", "null" ], "description": "The scheme of the first URI: https, http, file, cdrom, tor or mirror.", "examples": [ "https" ] }, "packages": { "type": "integer", "description": "Installed packages whose installed version this repository offers.", "examples": [ 42 ] }, "vendor": { "type": "object", "description": "Who publishes it, classified from the URIs.", "properties": { "slug": { "type": "string", "description": "Vendor slug such as debian, ubuntu-esm, sury, freexian, epel, ppa:ondrej\/php, or other: for an unknown host. Use it in repo: queries. New values may be added.", "examples": [ "sury" ] }, "label": { "type": "string", "examples": [ "Sury" ] }, "kind": { "description": "distro for the distribution's own archives, third_party otherwise. Distribution advisories are not matched against packages only third-party repositories offer.\n| |\n|---|\n| `distro` The distribution's own archives, security advisories cover their packages. |\n| `third_party` Anyone else: Sury, NodeSource, Docker, PPAs, a vendor's own repository or an unknown host. |", "$ref": "#\/components\/schemas\/RepositoryVendorKind" } }, "required": [ "slug", "label", "kind" ] }, "issues": { "type": "array", "description": "Checks the repository fails, insecure ones first.", "items": { "$ref": "#\/components\/schemas\/RepositoryIssueDetails" } }, "first_seen_at": { "type": "string", "description": "ISO 8601 timestamp the repository was first reported." } }, "required": [ "id", "file", "type", "enabled", "uris", "suite", "components", "name", "signing", "transport", "packages", "vendor", "issues", "first_seen_at" ], "title": "ServerRepository" }, "ServerSoftware": { "type": "object", "properties": { "product": { "type": "string", "description": "Normalised product name, such as php, mysql, mariadb, nginx, apache, openssl, kernel, nodejs, redis or postgresql. New products may be added.", "examples": [ "php" ] }, "version": { "type": "string", "description": "Upstream version without epoch or distribution revision, product filters such as php:7.4 match on it.", "examples": [ "7.4.33" ] }, "package_version": { "type": [ "string", "null" ], "description": "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.", "examples": [ "7.4.33-1+ubuntu16.04.1+deb.sury.org+1" ] }, "manager": { "type": [ "string", "null" ], "description": "Package manager of that package, dpkg or rpm. Null for a PHP build without a package.", "examples": [ "dpkg" ] }, "major": { "type": "integer", "examples": [ 7 ] }, "minor": { "type": [ "integer", "null" ], "examples": [ 4 ] }, "patch": { "type": [ "integer", "null" ], "examples": [ 33 ] }, "package": { "type": [ "string", "null" ], "description": "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.", "examples": [ "php7.4-fpm" ] }, "source": { "type": "string", "description": "package when a package provides it, build for PHP built without one, such as a DirectAdmin custombuild or a source build.", "examples": [ "package" ] }, "is_eol": { "type": "boolean", "description": "Whether this release cycle is past its end of life according to endoflife.date." }, "eol_at": { "type": [ "string", "null" ], "description": "End-of-life date of the release cycle, or null when unknown." } }, "required": [ "product", "version", "package_version", "manager", "major", "minor", "patch", "package", "source", "is_eol", "eol_at" ], "title": "ServerSoftware" }, "ServerStatus": { "type": "string", "description": "| |\n|---|\n| `pending` Created in the dashboard, the agent has not enrolled yet. |\n| `active` The agent enrolled and reported in within the offline threshold. |\n| `offline` The agent has not reported in within the offline threshold. |", "x-extensible-enum": [ "pending", "active", "offline" ], "title": "ServerStatus" }, "ServerStorageHealthyEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A server's storage is healthy again.", "enum": [ "server.storage_healthy" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Server" }, "unhealthy_since": { "type": "string", "format": "date-time", "description": "When the storage stopped being healthy." } }, "required": [ "object", "unhealthy_since" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "ServerStorageHealthyEvent" }, "ServerStorageUnhealthyEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A RAID array or ZFS pool degraded, or a disk failed.", "enum": [ "server.storage_unhealthy" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Server" }, "health": { "description": "How bad it is: `degraded` while redundancy keeps the data available, `failed` when data is not available.\n| |\n|---|\n| `healthy` Every array and pool has all its devices without errors and every disk works. |\n| `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. |\n| `failed` An array or pool stopped, files have permanent errors, or a disk outside any array or pool failed: data is unavailable. |", "$ref": "#\/components\/schemas\/StorageHealth" }, "problems": { "type": "array", "description": "What is wrong: each problem's own health, the array, pool or disk it is about, and a description to show to a person.", "items": { "type": "object", "properties": { "health": { "$ref": "#\/components\/schemas\/StorageHealth" }, "subject": { "type": "string" }, "description": { "type": "string" } }, "required": [ "health", "subject", "description" ] } }, "unhealthy_since": { "type": "string", "format": "date-time", "description": "When the storage stopped being healthy." } }, "required": [ "object", "health", "problems", "unhealthy_since" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "ServerStorageUnhealthyEvent" }, "ServerTag": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted tag ID.", "examples": [ "tag_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "production" ] }, "color": { "$ref": "#\/components\/schemas\/TagColor" } }, "required": [ "id", "name", "color" ], "title": "ServerTag" }, "ServerUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A server's name, metadata, location or settings changed.", "enum": [ "server.updated" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "description": "The resource the event is about, as the API returns it at the time of the event.", "$ref": "#\/components\/schemas\/Server" } }, "required": [ "object" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "ServerUpdatedEvent" }, "ServerVhost": { "type": "object", "properties": { "server": { "type": "object", "description": "The server hosting the site, only included when searching sites across servers.", "properties": { "id": { "type": "string", "description": "Formatted server ID.", "examples": [ "server_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "web-01" ] } }, "required": [ "id", "name" ] }, "source": { "type": "string", "description": "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.", "examples": [ "apache" ] }, "name": { "type": "string", "description": "Primary server name, in lower case.", "examples": [ "shop.example.com" ] }, "aliases": { "type": "array", "description": "Other names the vhost answers to, sorted and in lower case. Wildcards are kept as configured.", "examples": [ [ "www.shop.example.com", "*.shop.example.com" ] ], "items": { "type": "string" } }, "ports": { "type": "array", "description": "Ports the vhost listens on, sorted.", "examples": [ [ 80, 443 ] ], "items": { "type": "integer" } }, "ssl": { "type": "boolean", "description": "Whether any of the ports serves TLS." }, "document_root": { "type": [ "string", "null" ], "description": "Document root, or null when the vhost has none.", "examples": [ "\/var\/www\/shop\/public" ] }, "php_version": { "type": [ "string", "null" ], "description": "PHP version the site runs as major.minor, or null when unknown or not PHP.", "examples": [ "8.2" ] }, "php_handler": { "type": [ "string", "null" ], "description": "How PHP runs: fpm, fastcgi, cgi, module or lsapi. New values may be added.", "examples": [ "fpm" ] }, "php": { "type": [ "object", "null" ], "description": "The PHP the site runs with its full installed version, null when unknown or not PHP.", "properties": { "version": { "type": "string", "description": "major.minor version the site reports.", "examples": [ "8.2" ] }, "resolved_version": { "type": [ "string", "null" ], "description": "Upstream version of the installed package or PHP build running it. Null for a custom build without a package (such as a DirectAdmin custombuild or a source build) whose version the agent could not read.", "examples": [ "8.2.35" ] }, "package": { "type": [ "string", "null" ], "description": "The package providing it, the one matching the handler when installed.", "examples": [ "php8.2-fpm" ] }, "package_version": { "type": [ "string", "null" ], "description": "Full version of that package.", "examples": [ "8.2.35-1~deb12u1" ] }, "is_eol": { "type": "boolean", "description": "Whether this PHP release is end of life." } }, "required": [ "version", "resolved_version", "package", "package_version", "is_eol" ] }, "certificate": { "type": [ "object", "null" ], "description": "The TLS certificate the vhost is configured with, null without one.", "properties": { "subject": { "type": [ "string", "null" ], "examples": [ "shop.example.com" ] }, "issuer": { "type": [ "string", "null" ], "examples": [ "R11" ] }, "not_after": { "type": "string", "description": "ISO 8601 timestamp the certificate expires at." }, "names": { "type": "array", "description": "Names the certificate covers.", "items": { "type": "string" } }, "fingerprint": { "type": [ "string", "null" ], "description": "SHA-256 of the certificate, the fingerprint of its entry in the server's certificates, null when the agent did not report it.", "examples": [ "3f6c1a9e0b7d4c2a8e5f1b3d7a9c0e2f4b6d8a1c3e5f7b9d0a2c4e6f8b1d3a5c" ] }, "expired": { "type": "boolean", "description": "Whether the certificate has expired." }, "days_left": { "type": [ "integer", "null" ], "description": "Whole days until the certificate expires, negative once it expired.", "examples": [ 42 ] } }, "required": [ "subject", "issuer", "not_after", "names", "fingerprint", "expired", "days_left" ] }, "config_file": { "type": [ "string", "null" ], "description": "Absolute path of the configuration file defining the vhost, null for panel entries without one.", "examples": [ "\/etc\/apache2\/sites-enabled\/shop.conf" ] }, "owner": { "type": [ "string", "null" ], "description": "Panel subscription or user owning the site, or on a plain web server the user whose home directory holds the document root, null otherwise.", "examples": [ "acme" ] }, "http2": { "type": "boolean", "description": "Whether the vhost offers HTTP\/2." }, "http3": { "type": "boolean", "description": "Whether the vhost offers HTTP\/3, over a QUIC listener." }, "https_redirect": { "type": "boolean", "description": "Whether plain HTTP requests for the site redirect to HTTPS." }, "redirect": { "type": [ "object", "null" ], "description": "Where the vhost redirects every request, null when it serves the site itself.", "properties": { "status": { "type": [ "integer", "null" ], "description": "The HTTP status of the redirect.", "examples": [ 301 ] }, "target": { "type": [ "string", "null" ], "description": "The target URL as configured, with its web server variables.", "examples": [ "https:\/\/new.example.com$request_uri" ] }, "host": { "type": [ "string", "null" ], "description": "The target's host name, null when the target keeps the requested host.", "examples": [ "new.example.com" ] } }, "required": [ "status", "target", "host" ] }, "url": { "type": "string", "description": "The site's page in Server Chief, shared by every source reporting the site.", "examples": [ "https:\/\/server.chief.app\/team\/acme\/sites\/01j8q8zk2f4m6n7p9r1s3t5v7x\/shop.example.com" ] } }, "required": [ "source", "name", "aliases", "ports", "ssl", "document_root", "php_version", "php_handler", "php", "certificate", "config_file", "owner", "http2", "http3", "https_redirect", "redirect", "url" ], "title": "ServerVhost" }, "ServerVulnerability": { "type": "object", "properties": { "server": { "type": "object", "description": "The affected server, only included when searching vulnerabilities across servers.", "properties": { "id": { "type": "string", "description": "Formatted server ID.", "examples": [ "server_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "web-01" ] } }, "required": [ "id", "name" ] }, "vulnerability_id": { "type": "string", "description": "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.", "examples": [ "CVE-2023-5363" ] }, "advisory_id": { "type": "string", "description": "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.", "examples": [ "DEBIAN-CVE-2023-5363" ] }, "advisory_ids": { "type": "array", "description": "Every advisory of the server's releases that covers this vulnerability for the package.", "examples": [ [ "DEBIAN-CVE-2023-5363", "DSA-5532-1" ] ], "items": { "type": "string" } }, "summary": { "type": [ "string", "null" ], "description": "Summary of the deciding advisory, or the start of its description.", "examples": [ "openssl - security update" ] }, "package": { "type": "string", "description": "Source package the advisory names. Debian and Ubuntu advisories name source packages, so one source covers all binary packages built from it.", "examples": [ "openssl" ] }, "binary_package": { "type": [ "string", "null" ], "description": "The installed binary package with the lowest affected version, null once it was removed.", "examples": [ "libssl3" ] }, "installed_version": { "type": "string", "description": "Installed version compared with the advisory: the source version when the agent reports it, otherwise the binary version.", "examples": [ "3.0.11-1~deb12u1" ] }, "fixed_version": { "type": [ "string", "null" ], "description": "First version with the fix, null when the distribution has not released one for the server's release.", "examples": [ "3.0.11-1~deb12u2" ] }, "fixed_release": { "type": [ "string", "null" ], "description": "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.", "examples": [ "debian:12" ] }, "requires_subscription": { "type": "boolean", "description": "Whether the fix needs a subscription, Ubuntu Pro (ESM)." }, "fix_status": { "description": "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.\n| |\n|---|\n| `available` The package manager offers an update to the fixed version or later, installing pending updates fixes it. |\n| `reboot` A newer installed kernel fixes it, rebooting into that kernel does. |\n| `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). |\n| `none` The distribution has not released a fix for the server's release. |", "$ref": "#\/components\/schemas\/VulnerabilityFixStatus" }, "severity": { "description": "Severity normalised across distributions: the distribution's rating when it has one, otherwise the CVSS v3 band.\n| |\n|---|\n| `critical` Ubuntu critical, Red Hat Critical, or a CVSS base score of 9.0 or higher. |\n| `high` Ubuntu high, Red Hat Important, Debian high, or a CVSS base score from 7.0. |\n| `medium` Ubuntu medium, Red Hat Moderate, Debian medium, or a CVSS base score from 4.0. |\n| `low` Ubuntu low, Red Hat Low, Debian low, or a CVSS base score below 4.0. |\n| `negligible` Ubuntu negligible or Debian unimportant: no practical impact on the distribution's builds. |\n| `unknown` Not rated yet. |", "$ref": "#\/components\/schemas\/AdvisorySeverity" }, "cvss_score": { "type": [ "number", "null" ], "description": "Highest CVSS v3 base score of the deciding advisories, null without a CVSS v3 vector.", "examples": [ 7.5 ] }, "known_exploited": { "type": "boolean", "description": "Whether CISA lists the CVE in its Known Exploited Vulnerabilities catalog: it is exploited in the wild, fix it first." }, "known_exploited_at": { "type": [ "string", "null" ], "description": "Date CISA added the CVE to its Known Exploited Vulnerabilities catalog, null when it is not listed.", "examples": [ "2026-10-27" ] }, "epss_score": { "type": [ "number", "null" ], "description": "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.", "examples": [ 0.04753 ] }, "epss_percentile": { "type": [ "number", "null" ], "description": "How the EPSS score ranks among all scored CVEs, 0 to 1: 0.95 is a higher score than 95% of them.", "examples": [ 0.91849 ] }, "public_exploit": { "type": "boolean", "description": "Whether Metasploit, Nuclei or Exploit-DB has a public exploit of the CVE, so attacking it takes little skill." }, "metasploit_module": { "type": [ "string", "null" ], "description": "Full name of a Metasploit Framework exploit or auxiliary module attacking the CVE, null when there is none.", "examples": [ "exploit\/linux\/http\/magento_xxe_to_glibc_buf_overflow" ] }, "nuclei_template": { "type": [ "string", "null" ], "description": "Path of a Nuclei template detecting the CVE in ProjectDiscovery's nuclei-templates repository, null when there is none.", "examples": [ "http\/cves\/2021\/CVE-2021-44228.yaml" ] }, "exploit_db_id": { "type": [ "integer", "null" ], "description": "ID of an exploit or proof of concept of the CVE on Exploit-DB, null when there is none.", "examples": [ 50973 ] }, "first_seen_at": { "type": "string", "description": "ISO 8601 timestamp the vulnerability was first found on the server." }, "resolved_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp the vulnerability was resolved, null while it is open." }, "resolved_version": { "type": [ "string", "null" ], "description": "Version of the source package when the vulnerability was resolved, null when the package was removed or it is open.", "examples": [ "3.0.11-1~deb12u2" ] } }, "required": [ "vulnerability_id", "advisory_id", "advisory_ids", "summary", "package", "binary_package", "installed_version", "fixed_version", "fixed_release", "requires_subscription", "fix_status", "severity", "cvss_score", "known_exploited", "known_exploited_at", "epss_score", "epss_percentile", "public_exploit", "metasploit_module", "nuclei_template", "exploit_db_id", "first_seen_at", "resolved_at", "resolved_version" ], "title": "ServerVulnerability" }, "ShareTagRequest": { "type": "object", "properties": { "team": { "type": "string", "description": "Slug of the team to share the tag with. The team must use Server Chief.", "examples": [ "acme" ], "maxLength": 255 }, "role": { "type": "string", "description": "What the team can do with the tagged servers. viewer is read-only.", "enum": [ "viewer" ], "default": "viewer" } }, "required": [ "team" ], "title": "ShareTagRequest" }, "StorageHealth": { "type": "string", "description": "Health of a server's software RAID arrays, ZFS pools and disks, from the agent's storage dataset.\n| |\n|---|\n| `healthy` Every array and pool has all its devices without errors and every disk works. |\n| `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. |\n| `failed` An array or pool stopped, files have permanent errors, or a disk outside any array or pool failed: data is unavailable. |", "x-extensible-enum": [ "healthy", "degraded", "failed" ], "title": "StorageHealth" }, "Tag": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted tag ID.", "examples": [ "tag_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "production" ] }, "color": { "$ref": "#\/components\/schemas\/TagColor" }, "owner_team": { "description": "The team that owns the tag and the servers carrying it.", "$ref": "#\/components\/schemas\/TeamReference" }, "access": { "description": "owner for the team's own tags, viewer for a tag another team shared with it.\n| |\n|---|\n| `owner` The team owns the server or tag: it manages it, and owns and is billed for servers. |\n| `viewer` Shared with the team through a tag: the team can view but not change it. |", "$ref": "#\/components\/schemas\/TeamAccess" }, "servers_count": { "type": "integer", "description": "Number of the owner's servers carrying the tag.", "examples": [ 4 ] }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "name", "color", "owner_team", "access", "servers_count", "created_at", "updated_at" ], "title": "Tag" }, "TagColor": { "type": "string", "x-extensible-enum": [ "zinc", "red", "orange", "amber", "green", "teal", "sky", "blue", "violet", "pink" ], "title": "TagColor" }, "TagShare": { "type": "object", "properties": { "team": { "description": "The team the tag is shared with.", "$ref": "#\/components\/schemas\/TeamReference" }, "role": { "description": "What the team can do with the tagged servers, viewer is read-only.\n| |\n|---|\n| `viewer` Read-only access to the tagged servers: inventory, packages, software and metadata. |", "$ref": "#\/components\/schemas\/TagShareRole" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of when the tag was shared." } }, "required": [ "team", "role", "created_at" ], "title": "TagShare" }, "TagShareRole": { "type": "string", "description": "| |\n|---|\n| `viewer` Read-only access to the tagged servers: inventory, packages, software and metadata. |", "x-extensible-enum": [ "viewer" ], "title": "TagShareRole" }, "TeamAccess": { "type": "string", "description": "| |\n|---|\n| `owner` The team owns the server or tag: it manages it, and owns and is billed for servers. |\n| `viewer` Shared with the team through a tag: the team can view but not change it. |", "x-extensible-enum": [ "owner", "viewer" ], "title": "TeamAccess" }, "TeamReference": { "type": "object", "properties": { "slug": { "type": "string", "description": "Team slug.", "examples": [ "acme" ] }, "name": { "type": "string", "examples": [ "Acme Inc" ] } }, "required": [ "slug", "name" ], "title": "TeamReference" }, "UpdateServerTagsRequest": { "type": "object", "properties": { "attach": { "type": "array", "description": "Tags to attach, by formatted ID or by name. Tags the server already carries are kept.", "examples": [ [ "production" ] ], "items": { "type": "string", "maxLength": 64 }, "maxItems": 50, "uniqueItems": true }, "detach": { "type": "array", "description": "Tags to detach, by formatted ID or by name.", "examples": [ [ "staging" ] ], "items": { "type": "string", "maxLength": 64 }, "maxItems": 50, "uniqueItems": true } }, "title": "UpdateServerTagsRequest" }, "UpdateWebhookEndpointRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS URL that receives the events, it must resolve to a public address.", "examples": [ "https:\/\/example.com\/webhooks\/chief" ], "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "description": "What the endpoint is for, shown in the dashboard. Null removes it.", "examples": [ "Paging" ], "maxLength": 255 }, "events": { "type": "array", "description": "Event types the endpoint receives, `*` for every event including types added later. Replaces the current list.", "examples": [ [ "*" ] ], "items": { "type": "string", "enum": [ "*", "server.created", "server.enrolled", "server.updated", "server.deleted", "server.offline", "server.online", "server.reboot_stalled", "alert.fired", "alert.resolved", "metrics.stalled", "metrics.resumed", "server.storage_unhealthy", "server.storage_healthy" ] }, "minItems": 1, "uniqueItems": true } }, "title": "UpdateWebhookEndpointRequest" }, "UpgradeServerPackagesRequest": { "type": "object", "properties": { "scope": { "type": "string", "description": "Which pending updates to install: the security updates or every update.", "enum": [ "security", "all" ] }, "restart_services": { "type": "boolean", "description": "Restart the services that use updated libraries afterwards, so the updates take effect without a reboot.", "default": true }, "reboot_if_required": { "type": "boolean", "description": "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 } }, "required": [ "scope" ], "title": "UpgradeServerPackagesRequest" }, "VulnerabilityFixStatus": { "type": "string", "description": "| |\n|---|\n| `available` The package manager offers an update to the fixed version or later, installing pending updates fixes it. |\n| `reboot` A newer installed kernel fixes it, rebooting into that kernel does. |\n| `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). |\n| `none` The distribution has not released a fix for the server's release. |", "x-extensible-enum": [ "available", "reboot", "released", "none" ], "title": "VulnerabilityFixStatus" }, "WebhookAttemptError": { "type": "string", "description": "Why an attempt failed without a usable response, an attempt with a non-2xx response has no error.\n| |\n|---|\n| `timeout` The endpoint did not answer within 15 seconds. |\n| `connection` The connection failed: DNS, refused, TLS. |\n| `blocked` The URL resolves to a private or reserved address. |\n| `redirect` The endpoint answered with a redirect, which is not followed. |", "x-extensible-enum": [ "timeout", "connection", "blocked", "redirect" ], "title": "WebhookAttemptError" }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted delivery ID.", "examples": [ "delivery_01m6v3f5b0c8z6w4k2t9r7p5n3" ] }, "endpoint_id": { "type": "string", "description": "ID of the endpoint it is sent to.", "examples": [ "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6" ] }, "event_id": { "type": "string", "description": "ID of the event it sends.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "event_type": { "description": "Type of the event it sends.\n| |\n|---|\n| `server.created` A server was added and waits for its agent. |\n| `server.enrolled` A server's agent enrolled for the first time. |\n| `server.updated` A server's name, metadata, location or settings changed. |\n| `server.deleted` A server was removed. |\n| `server.offline` A server stopped checking in. |\n| `server.online` An offline server checks in again. |\n| `server.reboot_stalled` A server did not come back after a reboot. |\n| `alert.fired` A metric alert rule fired. |\n| `alert.resolved` A firing alert resolved. |\n| `metrics.stalled` An online server stopped delivering metrics. |\n| `metrics.resumed` A server delivers metrics again. |\n| `server.storage_unhealthy` A RAID array or ZFS pool degraded, or a disk failed. |\n| `server.storage_healthy` A server's storage is healthy again. |\n| `webhook_endpoint.test` A test event sent from the dashboard. |", "$ref": "#\/components\/schemas\/WebhookEventType" }, "status": { "$ref": "#\/components\/schemas\/WebhookDeliveryStatus" }, "attempts": { "type": "integer", "description": "Attempts made so far, resends included." }, "next_attempt_at": { "type": [ "string", "null" ], "description": "ISO 8601 time the next automatic attempt is due, null when none is scheduled." }, "last_attempted_at": { "type": [ "string", "null" ], "description": "ISO 8601 time of the last attempt, null before the first." }, "last_response_status": { "type": [ "integer", "null" ], "description": "HTTP status of the last response, null before the first attempt or when no response came." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "attempt_log": { "type": "array", "description": "Every attempt with its request and response, oldest first. Only returned for a single delivery.", "items": { "$ref": "#\/components\/schemas\/WebhookDeliveryAttempt" } } }, "required": [ "id", "endpoint_id", "event_id", "event_type", "status", "attempts", "next_attempt_at", "last_attempted_at", "last_response_status", "created_at" ], "title": "WebhookDelivery" }, "WebhookDeliveryAttempt": { "type": "object", "properties": { "number": { "type": "integer", "description": "Number of the attempt within its delivery, from 1." }, "manual": { "type": "boolean", "description": "Whether someone resent it, instead of an automatic attempt." }, "succeeded": { "type": "boolean", "description": "Whether the endpoint answered with a `2xx` status in time." }, "attempted_at": { "type": "string", "description": "ISO 8601 time the request was sent." }, "duration_ms": { "type": [ "integer", "null" ], "description": "How long the request took, null when it could not be sent." }, "error": { "anyOf": [ { "description": "Why the attempt failed without a usable response, null when a response came.\n| |\n|---|\n| `timeout` The endpoint did not answer within 15 seconds. |\n| `connection` The connection failed: DNS, refused, TLS. |\n| `blocked` The URL resolves to a private or reserved address. |\n| `redirect` The endpoint answered with a redirect, which is not followed. |", "$ref": "#\/components\/schemas\/WebhookAttemptError" }, { "type": "null" } ] }, "error_message": { "type": [ "string", "null" ], "description": "What went wrong, for people." }, "request": { "type": "object", "properties": { "headers": { "type": "object", "description": "Headers of the request, signature included. The body is the event's payload.", "additionalProperties": { "type": "string" } } }, "required": [ "headers" ] }, "response": { "type": [ "object", "null" ], "description": "The endpoint's response, null when none came.", "properties": { "status": { "type": "integer", "description": "HTTP status of the response." }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": [ "string", "null" ], "description": "Start of the response body, null for a compressed body that could not be read." }, "truncated": { "type": "boolean", "description": "Whether the body was cut off at the kept size." } }, "required": [ "status", "headers", "body", "truncated" ] } }, "required": [ "number", "manual", "succeeded", "attempted_at", "duration_ms", "error", "error_message", "request", "response" ], "title": "WebhookDeliveryAttempt" }, "WebhookDeliveryStatus": { "type": "string", "description": "| |\n|---|\n| `pending` Waiting for its first attempt or for a retry. |\n| `succeeded` The endpoint answered with a 2xx status. |\n| `failed` Every attempt failed. |\n| `cancelled` The endpoint was disabled or deleted before it succeeded. |", "x-extensible-enum": [ "pending", "succeeded", "failed", "cancelled" ], "title": "WebhookDeliveryStatus" }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted endpoint ID.", "examples": [ "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6" ] }, "url": { "type": "string", "description": "HTTPS URL that receives the events.", "examples": [ "https:\/\/example.com\/webhooks\/chief" ] }, "description": { "type": [ "string", "null" ], "description": "What the endpoint is for.", "examples": [ "Paging" ] }, "events": { "type": "array", "description": "Event types the endpoint receives, `*` for every event including types added later.", "examples": [ [ "server.offline", "server.online" ] ], "items": { "anyOf": [ { "$ref": "#\/components\/schemas\/WebhookEventType" }, { "type": "string", "enum": [ "*" ] } ] } }, "status": { "description": "Whether deliveries are sent. A disabled endpoint receives nothing until it is enabled again.\n| |\n|---|\n| `enabled` Receives the events it subscribed to. |\n| `disabled` Receives nothing until someone enables it again, `disabled_reason` tells why. |", "$ref": "#\/components\/schemas\/WebhookEndpointStatus" }, "disabled_reason": { "anyOf": [ { "description": "Why the endpoint was disabled, null while it is enabled.\n| |\n|---|\n| `manual` Someone disabled it. |\n| `failing` Every delivery failed for five days, so it was disabled automatically. |", "$ref": "#\/components\/schemas\/WebhookEndpointDisabledReason" }, { "type": "null" } ] }, "disabled_at": { "type": [ "string", "null" ], "description": "ISO 8601 time the endpoint was disabled, null while it is enabled." }, "failing_since": { "type": [ "string", "null" ], "description": "ISO 8601 time the endpoint started failing every delivery, null while deliveries succeed. It is disabled after five days." }, "secret": { "type": [ "string", "null" ], "description": "Signing secret, only set in the response that creates the endpoint or rotates its secret, null otherwise. Store it with your other secrets.", "examples": [ "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" ] }, "previous_secret_expires_at": { "type": [ "string", "null" ], "description": "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": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of the last change." } }, "required": [ "id", "url", "description", "events", "status", "disabled_reason", "disabled_at", "failing_since", "secret", "previous_secret_expires_at", "created_at", "updated_at" ], "title": "WebhookEndpoint" }, "WebhookEndpointDisabledReason": { "type": "string", "description": "| |\n|---|\n| `manual` Someone disabled it. |\n| `failing` Every delivery failed for five days, so it was disabled automatically. |", "x-extensible-enum": [ "manual", "failing" ], "title": "WebhookEndpointDisabledReason" }, "WebhookEndpointStatus": { "type": "string", "description": "| |\n|---|\n| `enabled` Receives the events it subscribed to. |\n| `disabled` Receives nothing until someone enables it again, `disabled_reason` tells why. |", "x-extensible-enum": [ "enabled", "disabled" ], "title": "WebhookEndpointStatus" }, "WebhookEndpointTestEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "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.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "type": "string", "description": "A test event sent from the dashboard.", "enum": [ "webhook_endpoint.test" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened, in UTC. It does not change on retries." }, "api_version": { "type": "string", "description": "The version of the payload format.", "examples": [ "v1" ] }, "data": { "type": "object", "properties": { "object": { "type": "object", "description": "The resource the event is about, as the API returns it at the time of the event.", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "description" ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "title": "WebhookEndpointTestEvent" }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted event ID, the same as `id` in the payload and the `webhook-id` header.", "examples": [ "event_01m6v3f5aydrktmzrbpz1pqh7e" ] }, "type": { "description": "Event type.\n| |\n|---|\n| `server.created` A server was added and waits for its agent. |\n| `server.enrolled` A server's agent enrolled for the first time. |\n| `server.updated` A server's name, metadata, location or settings changed. |\n| `server.deleted` A server was removed. |\n| `server.offline` A server stopped checking in. |\n| `server.online` An offline server checks in again. |\n| `server.reboot_stalled` A server did not come back after a reboot. |\n| `alert.fired` A metric alert rule fired. |\n| `alert.resolved` A firing alert resolved. |\n| `metrics.stalled` An online server stopped delivering metrics. |\n| `metrics.resumed` A server delivers metrics again. |\n| `server.storage_unhealthy` A RAID array or ZFS pool degraded, or a disk failed. |\n| `server.storage_healthy` A server's storage is healthy again. |\n| `webhook_endpoint.test` A test event sent from the dashboard. |", "$ref": "#\/components\/schemas\/WebhookEventType" }, "api_version": { "type": "string", "description": "Version of the payload format.", "examples": [ "v1" ] }, "created_at": { "type": "string", "description": "ISO 8601 time the event happened." }, "payload": { "type": "object", "description": "The body every delivery of the event sends, see the event's schema for its fields.", "additionalProperties": {} }, "deliveries": { "type": "array", "description": "The event's deliveries, one per endpoint. Only returned for a single event.", "items": { "$ref": "#\/components\/schemas\/WebhookDelivery" } } }, "required": [ "id", "type", "api_version", "created_at", "payload" ], "title": "WebhookEvent" }, "WebhookEventType": { "type": "string", "description": "| |\n|---|\n| `server.created` A server was added and waits for its agent. |\n| `server.enrolled` A server's agent enrolled for the first time. |\n| `server.updated` A server's name, metadata, location or settings changed. |\n| `server.deleted` A server was removed. |\n| `server.offline` A server stopped checking in. |\n| `server.online` An offline server checks in again. |\n| `server.reboot_stalled` A server did not come back after a reboot. |\n| `alert.fired` A metric alert rule fired. |\n| `alert.resolved` A firing alert resolved. |\n| `metrics.stalled` An online server stopped delivering metrics. |\n| `metrics.resumed` A server delivers metrics again. |\n| `server.storage_unhealthy` A RAID array or ZFS pool degraded, or a disk failed. |\n| `server.storage_healthy` A server's storage is healthy again. |\n| `webhook_endpoint.test` A test event sent from the dashboard. |", "x-extensible-enum": [ "server.created", "server.enrolled", "server.updated", "server.deleted", "server.offline", "server.online", "server.reboot_stalled", "alert.fired", "alert.resolved", "metrics.stalled", "metrics.resumed", "server.storage_unhealthy", "server.storage_healthy", "webhook_endpoint.test" ], "title": "WebhookEventType" }, "WebhookEventTypeDetails": { "type": "object", "properties": { "type": { "description": "Event type, as `type` in the payload and in an endpoint's `events`.\n| |\n|---|\n| `server.created` A server was added and waits for its agent. |\n| `server.enrolled` A server's agent enrolled for the first time. |\n| `server.updated` A server's name, metadata, location or settings changed. |\n| `server.deleted` A server was removed. |\n| `server.offline` A server stopped checking in. |\n| `server.online` An offline server checks in again. |\n| `server.reboot_stalled` A server did not come back after a reboot. |\n| `alert.fired` A metric alert rule fired. |\n| `alert.resolved` A firing alert resolved. |\n| `metrics.stalled` An online server stopped delivering metrics. |\n| `metrics.resumed` A server delivers metrics again. |\n| `server.storage_unhealthy` A RAID array or ZFS pool degraded, or a disk failed. |\n| `server.storage_healthy` A server's storage is healthy again. |\n| `webhook_endpoint.test` A test event sent from the dashboard. |", "$ref": "#\/components\/schemas\/WebhookEventType" }, "group": { "type": "string", "description": "Heading the event is listed under in the dashboard.", "examples": [ "Availability" ] }, "description": { "type": "string", "description": "When the event is sent.", "examples": [ "A server stopped checking in." ] } }, "required": [ "type", "group", "description" ], "title": "WebhookEventTypeDetails" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } }, "parameters": { "WebhookId": { "name": "webhook-id", "in": "header", "required": true, "description": "The event's `id`, the same on every attempt.", "schema": { "type": "string" } }, "WebhookTimestamp": { "name": "webhook-timestamp", "in": "header", "required": true, "description": "The Unix time this attempt was sent, reject requests more than five minutes from your clock.", "schema": { "type": "string" } }, "WebhookSignature": { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated `v1,{base64}` HMAC-SHA256 signatures of `{webhook-id}.{webhook-timestamp}.{body}`, following Standard Webhooks. Two while a rotated secret is still valid.", "schema": { "type": "string" } } } } }