Servers

Download schema

Endpoints for managing the servers in the team inventory.

List servers

GET

https://server.chief.app/api/v1

/servers

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

List servers › query Parameters

q

string | null · maxLength: 255

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:openssl3.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.

per_page

integer · min: 1 · max: 100

page

integer · min: 1

object

Filter by metadata key/value pairs, every pair must match exactly, for example metadata[customer]=acme.

List servers › Responses

Paginated set of Server

Server[] · required

object · required

GET/servers

curl https://server.chief.app/api/v1/servers \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "web-01",
      "hostname": "web-01.example.com",
      "owner_team": {
        "slug": "acme",
        "name": "Acme Inc"
      },
      "access": "owner",
      "tags": [
        {
          "id": "tag_01j8q8zk2f4m6n7p9r1s3t5v7x",
          "name": "production",
          "color": "zinc"
        }
      ],
      "metadata": {
        "key": "string"
      },
      "status": "pending",
      "agent_version": "1.0.0",
      "agent": {
        "version": "1.0.0",
        "update_available": true,
        "auto_updates": {
          "enabled": true,
          "is_default": true
        },
        "capability": {
          "available": true,
          "reason": "installed from a tarball"
        },
        "reboot": {
          "available": true,
          "reason": "running in a Docker container"
        },
        "upgrade_packages": {
          "available": true,
          "reason": "the root helper does not answer"
        },
        "disabled_actions": [
          "reboot"
        ]
      },
      "last_contact_at": "last_contact_at",
      "fqdn": "web-01.example.com",
      "os_family": "debian",
      "os_id": "ubuntu",
      "os_name": "Ubuntu",
      "os_version": "24.04.1",
      "os_codename": "noble",
      "kernel_release": "6.8.0-45-generic",
      "arch": "amd64",
      "virtualization": "guest/kvm",
      "boot_time": "boot_time",
      "cpu_model": "AMD EPYC 7763 64-Core Processor",
      "cpu_cores": 4,
      "cpu_threads": 8,
      "memory_bytes": 17179869184,
      "swap_bytes": 0,
      "disk_bytes": 0,
      "storage_health": "healthy",
      "storage_unhealthy_since": "storage_unhealthy_since",
      "public_ipv4": "203.0.113.10",
      "public_ipv6": "2001:db8::10",
      "observed_ip": "198.51.100.7",
      "nameservers": [
        "string"
      ],
      "addresses": [
        {
          "interface": "eth0",
          "address": "203.0.113.10",
          "prefix": 24,
          "family": 4,
          "scope": "public"
        }
      ],
      "is_os_eol": true,
      "os_eol_at": "os_eol_at",
      "pending_updates_count": 12,
      "security_updates_count": 3,
      "reboot_required": true,
      "updates_checked_at": "updates_checked_at",
      "package_metadata_refresh": {
        "enabled": true,
        "interval": 21600,
        "is_default": true
      },
      "software": [
        {
          "product": "php",
          "version": "7.4.33",
          "package_version": "7.4.33-1+ubuntu16.04.1+deb.sury.org+1",
          "manager": "dpkg",
          "major": 7,
          "minor": 4,
          "patch": 33,
          "package": "php7.4-fpm",
          "source": "package",
          "is_eol": true,
          "eol_at": "eol_at"
        }
      ],
      "provider": "hetzner",
      "city": "Falkenstein",
      "country": "DE",
      "continent": "EU",
      "location_source": "agent",
      "cloud_region": "fsn1",
      "cloud_zone": "fsn1-dc14",
      "instance_type": "m6i.large",
      "asn": 24940,
      "asn_org": "Hetzner Online GmbH",
      "location_override": {
        "provider": "hetzner",
        "city": "Falkenstein",
        "country": "DE",
        "continent": "EU"
      },
      "vhosts_count": 12,
      "certificates_count": 4,
      "certificate_issues_count": 1,
      "repositories": {
        "count": 8,
        "third_party_count": 3,
        "issues_count": 1,
        "orphaned_packages_count": 2,
        "not_covered_packages_count": 4,
        "vendors": [
          {
            "slug": "slug",
            "label": "label",
            "kind": "distro",
            "repositories": 0,
            "issues": [
              "insecure_trusted"
            ]
          }
        ]
      },
      "vulnerabilities": {
        "release": "debian:12",
        "critical": 2,
        "high": 5,
        "medium": 12,
        "low": 20,
        "negligible": 30,
        "unknown": 1,
        "total": 70,
        "fixable": 9,
        "reboot": 1,
        "subscription": 3,
        "released": 0,
        "unfixed": 57,
        "checked_at": "checked_at"
      },
      "enrollment": {
        "token": "scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
        "install_command": "curl -fsSL https://pkg.server.chief.app/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
        "expires_at": "expires_at"
      },
      "created_at": "created_at",
      "updated_at": "updated_at"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

Create a server

POST

https://server.chief.app/api/v1

/servers

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Create a server › Request Body

SaveServerRequest

name

string · maxLength: 255 · required

Human-readable server name.

Example: web-01

hostname

string | null · maxLength: 255

Hostname of the server, or null to clear it.

Example: web-01.example.com

object

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

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

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

tags

string[] · maxItems: 50 · unique

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

Example: ["production","tag_01j8q8zk2f4m6n7p9r1s3t5v7x"]

object

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

object

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

object

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

Create a server › Responses

The server was created.

Server · required

POST/servers

curl https://server.chief.app/api/v1/servers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "web-01",
  "hostname": "web-01.example.com",
  "metadata": {
    "customer": "acme",
    "environment": "production"
  },
  "tags": [
    "production",
    "tag_01j8q8zk2f4m6n7p9r1s3t5v7x"
  ],
  "location_override": {
    "provider": "hetzner",
    "city": "Falkenstein",
    "country": "DE",
    "continent": "EU"
  },
  "package_metadata_refresh": {
    "enabled": true
  },
  "agent_auto_updates": {
    "enabled": true
  }
}'

Example Request Body

{
  "name": "web-01",
  "hostname": "web-01.example.com",
  "metadata": {
    "customer": "acme",
    "environment": "production"
  },
  "tags": [
    "production",
    "tag_01j8q8zk2f4m6n7p9r1s3t5v7x"
  ],
  "location_override": {
    "provider": "hetzner",
    "city": "Falkenstein",
    "country": "DE",
    "continent": "EU"
  },
  "package_metadata_refresh": {
    "enabled": true
  },
  "agent_auto_updates": {
    "enabled": true
  }
}

json

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "web-01",
    "hostname": "web-01.example.com",
    "owner_team": {
      "slug": "acme",
      "name": "Acme Inc"
    },
    "access": "owner",
    "tags": [
      {
        "id": "tag_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "production",
        "color": "zinc"
      }
    ],
    "metadata": {
      "key": "string"
    },
    "status": "pending",
    "agent_version": "1.0.0",
    "agent": {
      "version": "1.0.0",
      "update_available": true,
      "auto_updates": {
        "enabled": true,
        "is_default": true
      },
      "capability": {
        "available": true,
        "reason": "installed from a tarball"
      },
      "reboot": {
        "available": true,
        "reason": "running in a Docker container"
      },
      "upgrade_packages": {
        "available": true,
        "reason": "the root helper does not answer"
      },
      "disabled_actions": [
        "reboot"
      ]
    },
    "last_contact_at": "last_contact_at",
    "fqdn": "web-01.example.com",
    "os_family": "debian",
    "os_id": "ubuntu",
    "os_name": "Ubuntu",
    "os_version": "24.04.1",
    "os_codename": "noble",
    "kernel_release": "6.8.0-45-generic",
    "arch": "amd64",
    "virtualization": "guest/kvm",
    "boot_time": "boot_time",
    "cpu_model": "AMD EPYC 7763 64-Core Processor",
    "cpu_cores": 4,
    "cpu_threads": 8,
    "memory_bytes": 17179869184,
    "swap_bytes": 0,
    "disk_bytes": 0,
    "storage_health": "healthy",
    "storage_unhealthy_since": "storage_unhealthy_since",
    "public_ipv4": "203.0.113.10",
    "public_ipv6": "2001:db8::10",
    "observed_ip": "198.51.100.7",
    "nameservers": [
      "string"
    ],
    "addresses": [
      {
        "interface": "eth0",
        "address": "203.0.113.10",
        "prefix": 24,
        "family": 4,
        "scope": "public"
      }
    ],
    "is_os_eol": true,
    "os_eol_at": "os_eol_at",
    "pending_updates_count": 12,
    "security_updates_count": 3,
    "reboot_required": true,
    "updates_checked_at": "updates_checked_at",
    "package_metadata_refresh": {
      "enabled": true,
      "interval": 21600,
      "is_default": true
    },
    "software": [
      {
        "product": "php",
        "version": "7.4.33",
        "package_version": "7.4.33-1+ubuntu16.04.1+deb.sury.org+1",
        "manager": "dpkg",
        "major": 7,
        "minor": 4,
        "patch": 33,
        "package": "php7.4-fpm",
        "source": "package",
        "is_eol": true,
        "eol_at": "eol_at"
      }
    ],
    "provider": "hetzner",
    "city": "Falkenstein",
    "country": "DE",
    "continent": "EU",
    "location_source": "agent",
    "cloud_region": "fsn1",
    "cloud_zone": "fsn1-dc14",
    "instance_type": "m6i.large",
    "asn": 24940,
    "asn_org": "Hetzner Online GmbH",
    "location_override": {
      "provider": "hetzner",
      "city": "Falkenstein",
      "country": "DE",
      "continent": "EU"
    },
    "vhosts_count": 12,
    "certificates_count": 4,
    "certificate_issues_count": 1,
    "repositories": {
      "count": 8,
      "third_party_count": 3,
      "issues_count": 1,
      "orphaned_packages_count": 2,
      "not_covered_packages_count": 4,
      "vendors": [
        {
          "slug": "slug",
          "label": "label",
          "kind": "distro",
          "repositories": 0,
          "issues": [
            "insecure_trusted"
          ]
        }
      ]
    },
    "vulnerabilities": {
      "release": "debian:12",
      "critical": 2,
      "high": 5,
      "medium": 12,
      "low": 20,
      "negligible": 30,
      "unknown": 1,
      "total": 70,
      "fixable": 9,
      "reboot": 1,
      "subscription": 3,
      "released": 0,
      "unfixed": 57,
      "checked_at": "checked_at"
    },
    "enrollment": {
      "token": "scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "install_command": "curl -fsSL https://pkg.server.chief.app/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "expires_at": "expires_at"
    },
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Show a server

GET

https://server.chief.app/api/v1

/servers/{server}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Show one server the authenticated team can see, including servers shared with it (access viewer).

Show a server › path Parameters

server

string · required

Show a server › Responses

Server

Server · required

GET/servers/{server}

curl https://server.chief.app/api/v1/servers/:server \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "web-01",
    "hostname": "web-01.example.com",
    "owner_team": {
      "slug": "acme",
      "name": "Acme Inc"
    },
    "access": "owner",
    "tags": [
      {
        "id": "tag_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "production",
        "color": "zinc"
      }
    ],
    "metadata": {
      "key": "string"
    },
    "status": "pending",
    "agent_version": "1.0.0",
    "agent": {
      "version": "1.0.0",
      "update_available": true,
      "auto_updates": {
        "enabled": true,
        "is_default": true
      },
      "capability": {
        "available": true,
        "reason": "installed from a tarball"
      },
      "reboot": {
        "available": true,
        "reason": "running in a Docker container"
      },
      "upgrade_packages": {
        "available": true,
        "reason": "the root helper does not answer"
      },
      "disabled_actions": [
        "reboot"
      ]
    },
    "last_contact_at": "last_contact_at",
    "fqdn": "web-01.example.com",
    "os_family": "debian",
    "os_id": "ubuntu",
    "os_name": "Ubuntu",
    "os_version": "24.04.1",
    "os_codename": "noble",
    "kernel_release": "6.8.0-45-generic",
    "arch": "amd64",
    "virtualization": "guest/kvm",
    "boot_time": "boot_time",
    "cpu_model": "AMD EPYC 7763 64-Core Processor",
    "cpu_cores": 4,
    "cpu_threads": 8,
    "memory_bytes": 17179869184,
    "swap_bytes": 0,
    "disk_bytes": 0,
    "storage_health": "healthy",
    "storage_unhealthy_since": "storage_unhealthy_since",
    "public_ipv4": "203.0.113.10",
    "public_ipv6": "2001:db8::10",
    "observed_ip": "198.51.100.7",
    "nameservers": [
      "string"
    ],
    "addresses": [
      {
        "interface": "eth0",
        "address": "203.0.113.10",
        "prefix": 24,
        "family": 4,
        "scope": "public"
      }
    ],
    "is_os_eol": true,
    "os_eol_at": "os_eol_at",
    "pending_updates_count": 12,
    "security_updates_count": 3,
    "reboot_required": true,
    "updates_checked_at": "updates_checked_at",
    "package_metadata_refresh": {
      "enabled": true,
      "interval": 21600,
      "is_default": true
    },
    "software": [
      {
        "product": "php",
        "version": "7.4.33",
        "package_version": "7.4.33-1+ubuntu16.04.1+deb.sury.org+1",
        "manager": "dpkg",
        "major": 7,
        "minor": 4,
        "patch": 33,
        "package": "php7.4-fpm",
        "source": "package",
        "is_eol": true,
        "eol_at": "eol_at"
      }
    ],
    "provider": "hetzner",
    "city": "Falkenstein",
    "country": "DE",
    "continent": "EU",
    "location_source": "agent",
    "cloud_region": "fsn1",
    "cloud_zone": "fsn1-dc14",
    "instance_type": "m6i.large",
    "asn": 24940,
    "asn_org": "Hetzner Online GmbH",
    "location_override": {
      "provider": "hetzner",
      "city": "Falkenstein",
      "country": "DE",
      "continent": "EU"
    },
    "vhosts_count": 12,
    "certificates_count": 4,
    "certificate_issues_count": 1,
    "repositories": {
      "count": 8,
      "third_party_count": 3,
      "issues_count": 1,
      "orphaned_packages_count": 2,
      "not_covered_packages_count": 4,
      "vendors": [
        {
          "slug": "slug",
          "label": "label",
          "kind": "distro",
          "repositories": 0,
          "issues": [
            "insecure_trusted"
          ]
        }
      ]
    },
    "vulnerabilities": {
      "release": "debian:12",
      "critical": 2,
      "high": 5,
      "medium": 12,
      "low": 20,
      "negligible": 30,
      "unknown": 1,
      "total": 70,
      "fixable": 9,
      "reboot": 1,
      "subscription": 3,
      "released": 0,
      "unfixed": 57,
      "checked_at": "checked_at"
    },
    "enrollment": {
      "token": "scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "install_command": "curl -fsSL https://pkg.server.chief.app/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "expires_at": "expires_at"
    },
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Update a server

PATCH

https://server.chief.app/api/v1

/servers/{server}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Update a server › path Parameters

server

string · required

Update a server › Request Body

SaveServerRequest

name

string · maxLength: 255 · required

Human-readable server name.

Example: web-01

hostname

string | null · maxLength: 255

Hostname of the server, or null to clear it.

Example: web-01.example.com

object

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

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

tags

string[] · maxItems: 50 · unique

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

Example: ["production","tag_01j8q8zk2f4m6n7p9r1s3t5v7x"]

object

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

object

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

object

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

Update a server › Responses

Server

Server · required

PATCH/servers/{server}

curl https://server.chief.app/api/v1/servers/:server \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "web-01",
  "hostname": "web-01.example.com",
  "metadata": {
    "customer": "acme",
    "environment": "production"
  },
  "tags": [
    "production",
    "tag_01j8q8zk2f4m6n7p9r1s3t5v7x"
  ],
  "location_override": {
    "provider": "hetzner",
    "city": "Falkenstein",
    "country": "DE",
    "continent": "EU"
  },
  "package_metadata_refresh": {
    "enabled": true
  },
  "agent_auto_updates": {
    "enabled": true
  }
}'

Example Request Body

{
  "name": "web-01",
  "hostname": "web-01.example.com",
  "metadata": {
    "customer": "acme",
    "environment": "production"
  },
  "tags": [
    "production",
    "tag_01j8q8zk2f4m6n7p9r1s3t5v7x"
  ],
  "location_override": {
    "provider": "hetzner",
    "city": "Falkenstein",
    "country": "DE",
    "continent": "EU"
  },
  "package_metadata_refresh": {
    "enabled": true
  },
  "agent_auto_updates": {
    "enabled": true
  }
}

json

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "web-01",
    "hostname": "web-01.example.com",
    "owner_team": {
      "slug": "acme",
      "name": "Acme Inc"
    },
    "access": "owner",
    "tags": [
      {
        "id": "tag_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "production",
        "color": "zinc"
      }
    ],
    "metadata": {
      "key": "string"
    },
    "status": "pending",
    "agent_version": "1.0.0",
    "agent": {
      "version": "1.0.0",
      "update_available": true,
      "auto_updates": {
        "enabled": true,
        "is_default": true
      },
      "capability": {
        "available": true,
        "reason": "installed from a tarball"
      },
      "reboot": {
        "available": true,
        "reason": "running in a Docker container"
      },
      "upgrade_packages": {
        "available": true,
        "reason": "the root helper does not answer"
      },
      "disabled_actions": [
        "reboot"
      ]
    },
    "last_contact_at": "last_contact_at",
    "fqdn": "web-01.example.com",
    "os_family": "debian",
    "os_id": "ubuntu",
    "os_name": "Ubuntu",
    "os_version": "24.04.1",
    "os_codename": "noble",
    "kernel_release": "6.8.0-45-generic",
    "arch": "amd64",
    "virtualization": "guest/kvm",
    "boot_time": "boot_time",
    "cpu_model": "AMD EPYC 7763 64-Core Processor",
    "cpu_cores": 4,
    "cpu_threads": 8,
    "memory_bytes": 17179869184,
    "swap_bytes": 0,
    "disk_bytes": 0,
    "storage_health": "healthy",
    "storage_unhealthy_since": "storage_unhealthy_since",
    "public_ipv4": "203.0.113.10",
    "public_ipv6": "2001:db8::10",
    "observed_ip": "198.51.100.7",
    "nameservers": [
      "string"
    ],
    "addresses": [
      {
        "interface": "eth0",
        "address": "203.0.113.10",
        "prefix": 24,
        "family": 4,
        "scope": "public"
      }
    ],
    "is_os_eol": true,
    "os_eol_at": "os_eol_at",
    "pending_updates_count": 12,
    "security_updates_count": 3,
    "reboot_required": true,
    "updates_checked_at": "updates_checked_at",
    "package_metadata_refresh": {
      "enabled": true,
      "interval": 21600,
      "is_default": true
    },
    "software": [
      {
        "product": "php",
        "version": "7.4.33",
        "package_version": "7.4.33-1+ubuntu16.04.1+deb.sury.org+1",
        "manager": "dpkg",
        "major": 7,
        "minor": 4,
        "patch": 33,
        "package": "php7.4-fpm",
        "source": "package",
        "is_eol": true,
        "eol_at": "eol_at"
      }
    ],
    "provider": "hetzner",
    "city": "Falkenstein",
    "country": "DE",
    "continent": "EU",
    "location_source": "agent",
    "cloud_region": "fsn1",
    "cloud_zone": "fsn1-dc14",
    "instance_type": "m6i.large",
    "asn": 24940,
    "asn_org": "Hetzner Online GmbH",
    "location_override": {
      "provider": "hetzner",
      "city": "Falkenstein",
      "country": "DE",
      "continent": "EU"
    },
    "vhosts_count": 12,
    "certificates_count": 4,
    "certificate_issues_count": 1,
    "repositories": {
      "count": 8,
      "third_party_count": 3,
      "issues_count": 1,
      "orphaned_packages_count": 2,
      "not_covered_packages_count": 4,
      "vendors": [
        {
          "slug": "slug",
          "label": "label",
          "kind": "distro",
          "repositories": 0,
          "issues": [
            "insecure_trusted"
          ]
        }
      ]
    },
    "vulnerabilities": {
      "release": "debian:12",
      "critical": 2,
      "high": 5,
      "medium": 12,
      "low": 20,
      "negligible": 30,
      "unknown": 1,
      "total": 70,
      "fixable": 9,
      "reboot": 1,
      "subscription": 3,
      "released": 0,
      "unfixed": 57,
      "checked_at": "checked_at"
    },
    "enrollment": {
      "token": "scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "install_command": "curl -fsSL https://pkg.server.chief.app/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "expires_at": "expires_at"
    },
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Delete a server

DELETE

https://server.chief.app/api/v1

/servers/{server}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Remove a server from the authenticated team's inventory. The agent credential is revoked, so the agent stops reporting.

Delete a server › path Parameters

server

string · required

Delete a server › Responses

The server was deleted.

string

Issue an enrollment token

POST

https://server.chief.app/api/v1

/servers/{server}/enrollment-token

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Issue an enrollment token › path Parameters

server

string · required

Issue an enrollment token › Responses

The token was issued.

ServerEnrollment · required

Refresh a server's inventory

POST

https://server.chief.app/api/v1

/servers/{server}/refresh

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Refresh a server's inventory › path Parameters

server

string · required

Refresh a server's inventory › Request Body

RefreshServerRequest

datasets

array | null · minItems: 1 · unique

Datasets to collect, or null for every enabled dataset.

Enum values:

applications

certificates

cloud

hardware

network

packages

repositories

resolvers

Example: ["packages","updates"]

Refresh a server's inventory › Responses

The command was queued.

ServerCommand · required

POST/servers/{server}/refresh

curl https://server.chief.app/api/v1/servers/:server/refresh \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "datasets": [
    "packages",
    "updates"
  ]
}'

Example Request Body

{
  "datasets": [
    "packages",
    "updates"
  ]
}

json

Example Responses

{
  "data": {
    "id": "command_01jb9a2c3d4e5f6g7h8j9k0m1n",
    "kind": "refresh_inventory",
    "status": "queued",
    "datasets": [
      "string"
    ],
    "version": "1.2.3",
    "detail": "detail",
    "update_result": {
      "code": "updated",
      "previous_version": "1.2.2",
      "target_version": "1.2.3",
      "installed_version": "1.2.3"
    },
    "reboot_result": {
      "code": "rebooted",
      "previous_boot_time": "previous_boot_time",
      "boot_time": "boot_time"
    },
    "upgrade_result": {
      "code": "upgraded",
      "scope": "security",
      "upgraded": 0,
      "held_back": 0,
      "reboot_required": true,
      "services_restarted": [
        "string"
      ],
      "agent_update": {
        "code": "code",
        "previous_version": "previous_version",
        "installed_version": "installed_version"
      }
    },
    "origin": "panel",
    "created_at": "created_at",
    "expires_at": "expires_at",
    "finished_at": "finished_at"
  }
}

json

application/json

Update a server's agent

POST

https://server.chief.app/api/v1

/servers/{server}/agent-update

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Update a server's agent › path Parameters

server

string · required

Update a server's agent › Responses

The command was queued.

ServerCommand · required

POST/servers/{server}/agent-update

curl https://server.chief.app/api/v1/servers/:server/agent-update \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "command_01jb9a2c3d4e5f6g7h8j9k0m1n",
    "kind": "refresh_inventory",
    "status": "queued",
    "datasets": [
      "string"
    ],
    "version": "1.2.3",
    "detail": "detail",
    "update_result": {
      "code": "updated",
      "previous_version": "1.2.2",
      "target_version": "1.2.3",
      "installed_version": "1.2.3"
    },
    "reboot_result": {
      "code": "rebooted",
      "previous_boot_time": "previous_boot_time",
      "boot_time": "boot_time"
    },
    "upgrade_result": {
      "code": "upgraded",
      "scope": "security",
      "upgraded": 0,
      "held_back": 0,
      "reboot_required": true,
      "services_restarted": [
        "string"
      ],
      "agent_update": {
        "code": "code",
        "previous_version": "previous_version",
        "installed_version": "installed_version"
      }
    },
    "origin": "panel",
    "created_at": "created_at",
    "expires_at": "expires_at",
    "finished_at": "finished_at"
  }
}

json

application/json

Reboot a server

POST

https://server.chief.app/api/v1

/servers/{server}/reboot

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Reboot a server › path Parameters

server

string · required

Reboot a server › Responses

The command was queued.

ServerCommand · required

POST/servers/{server}/reboot

curl https://server.chief.app/api/v1/servers/:server/reboot \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "command_01jb9a2c3d4e5f6g7h8j9k0m1n",
    "kind": "refresh_inventory",
    "status": "queued",
    "datasets": [
      "string"
    ],
    "version": "1.2.3",
    "detail": "detail",
    "update_result": {
      "code": "updated",
      "previous_version": "1.2.2",
      "target_version": "1.2.3",
      "installed_version": "1.2.3"
    },
    "reboot_result": {
      "code": "rebooted",
      "previous_boot_time": "previous_boot_time",
      "boot_time": "boot_time"
    },
    "upgrade_result": {
      "code": "upgraded",
      "scope": "security",
      "upgraded": 0,
      "held_back": 0,
      "reboot_required": true,
      "services_restarted": [
        "string"
      ],
      "agent_update": {
        "code": "code",
        "previous_version": "previous_version",
        "installed_version": "installed_version"
      }
    },
    "origin": "panel",
    "created_at": "created_at",
    "expires_at": "expires_at",
    "finished_at": "finished_at"
  }
}

json

application/json

Install a server's package updates

POST

https://server.chief.app/api/v1

/servers/{server}/package-upgrades

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Install a server's package updates › path Parameters

server

string · required

Install a server's package updates › Request Body

UpgradeServerPackagesRequest

scope

string · enum · required

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

Enum values:

security

all

restart_services

boolean

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

Default: true

reboot_if_required

boolean

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

Default: false

Install a server's package updates › Responses

The command was queued.

ServerCommand · required

POST/servers/{server}/package-upgrades

curl https://server.chief.app/api/v1/servers/:server/package-upgrades \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "scope": "security",
  "restart_services": true,
  "reboot_if_required": false
}'

Example Request Body

{
  "scope": "security",
  "restart_services": true,
  "reboot_if_required": false
}

json

Example Responses

{
  "data": {
    "id": "command_01jb9a2c3d4e5f6g7h8j9k0m1n",
    "kind": "refresh_inventory",
    "status": "queued",
    "datasets": [
      "string"
    ],
    "version": "1.2.3",
    "detail": "detail",
    "update_result": {
      "code": "updated",
      "previous_version": "1.2.2",
      "target_version": "1.2.3",
      "installed_version": "1.2.3"
    },
    "reboot_result": {
      "code": "rebooted",
      "previous_boot_time": "previous_boot_time",
      "boot_time": "boot_time"
    },
    "upgrade_result": {
      "code": "upgraded",
      "scope": "security",
      "upgraded": 0,
      "held_back": 0,
      "reboot_required": true,
      "services_restarted": [
        "string"
      ],
      "agent_update": {
        "code": "code",
        "previous_version": "previous_version",
        "installed_version": "installed_version"
      }
    },
    "origin": "panel",
    "created_at": "created_at",
    "expires_at": "expires_at",
    "finished_at": "finished_at"
  }
}

json

application/json

List a server's packages

GET

https://server.chief.app/api/v1

/servers/{server}/packages

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the packages installed on a server, sorted by name, with the version a pending update would install.

List a server's packages › path Parameters

server

string · required

List a server's packages › query Parameters

name

string | null · maxLength: 255

Filter by package name, a substring match unless it contains * as a wildcard.

updates

boolean

Only return packages with a pending update.

origin

string | null · maxLength: 191 · pattern: ^[a-z0-9][a-z0-9._:\…

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.

per_page

integer · min: 1 · max: 100

page

integer · min: 1

List a server's packages › Responses

Paginated set of ServerPackage

ServerPackage[] · required

object · required

GET/servers/{server}/packages

curl https://server.chief.app/api/v1/servers/:server/packages \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "server": {
        "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "web-01"
      },
      "manager": "dpkg",
      "name": "openssl",
      "arch": "amd64",
      "version": "1.0.2g-1ubuntu4.20",
      "upstream_version": "1.0.2g",
      "source": "util-linux",
      "source_version": "2.36-9+deb12u4",
      "candidate_version": "1.0.2g-1ubuntu4.21",
      "is_security": true,
      "origins": [
        "bookworm:c4a17d93"
      ],
      "origin_vendor": "sury",
      "origin_kind": "distro"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

List a server's software

GET

https://server.chief.app/api/v1

/servers/{server}/software

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

List a server's software › path Parameters

server

string · required

List a server's software › Responses

Array of ServerSoftware

ServerSoftware[] · required

List a server's sites

GET

https://server.chief.app/api/v1

/servers/{server}/vhosts

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

List a server's sites › path Parameters

server

string · required

List a server's sites › query Parameters

domain

string | null · maxLength: 255

Only return sites serving this domain, by name or alias. A host also matches wildcard aliases covering it, and *.example.com matches every subdomain.

per_page

integer · min: 1 · max: 100

page

integer · min: 1

List a server's sites › Responses

Paginated set of ServerVhost

ServerVhost[] · required

object · required

GET/servers/{server}/vhosts

curl https://server.chief.app/api/v1/servers/:server/vhosts \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "server": {
        "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "web-01"
      },
      "source": "apache",
      "name": "shop.example.com",
      "aliases": [
        "www.shop.example.com",
        "*.shop.example.com"
      ],
      "ports": [
        80,
        443
      ],
      "ssl": true,
      "document_root": "/var/www/shop/public",
      "php_version": "8.2",
      "php_handler": "fpm",
      "php": {
        "version": "8.2",
        "resolved_version": "8.2.35",
        "package": "php8.2-fpm",
        "package_version": "8.2.35-1~deb12u1",
        "is_eol": true
      },
      "certificate": {
        "subject": "shop.example.com",
        "issuer": "R11",
        "not_after": "not_after",
        "names": [
          "string"
        ],
        "fingerprint": "3f6c1a9e0b7d4c2a8e5f1b3d7a9c0e2f4b6d8a1c3e5f7b9d0a2c4e6f8b1d3a5c",
        "expired": true,
        "days_left": 42
      },
      "config_file": "/etc/apache2/sites-enabled/shop.conf",
      "owner": "acme",
      "http2": true,
      "http3": true,
      "https_redirect": true,
      "redirect": {
        "status": 301,
        "target": "https://new.example.com$request_uri",
        "host": "new.example.com"
      },
      "url": "https://server.chief.app/team/acme/sites/01j8q8zk2f4m6n7p9r1s3t5v7x/shop.example.com"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

List a server's certificates

GET

https://server.chief.app/api/v1

/servers/{server}/certificates

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

List a server's certificates › path Parameters

server

string · required

List a server's certificates › query Parameters

query

string | null · maxLength: 255

Only return certificates whose names, subject, issuer, CA, manager, lineage or plugin contain this text.

issue

string | null · enum

Only return certificates failing this check.

Enum values:

expiring_unmanaged

renewal_missing

staging_ca

self_signed_public

incomplete_chain

weak_key

names_not_covered

duplicate

has_issues

boolean | null

Only return certificates failing at least one check.

severity

string | null · enum

Only return certificates whose most severe issue has this severity or worse.

Enum values:

high

medium

low

expiring_days

integer | null · min: 0 · max: 3650

Only return certificates that expire within this many days, including certificates that already expired. 0 returns expired certificates only.

manager

string | null · enum

Only return certificates issued and renewed by this tool.

Enum values:

certbot

acme.sh

plesk

directadmin

forge

unmanaged

boolean | null

Only return certificates without renewal automation: none was found, or the agent could not tell.

ca

string | null · maxLength: 32

Only return certificates of this CA: letsencrypt, letsencrypt-staging, zerossl, buypass, google or sectigo. New values may be added.

plugin

string | null · maxLength: 64

Only return certificates issued with this certbot or acme.sh plugin.

sort

string | null · enum

urgency lists the most severe issues first and then the soonest expiry, expiry the soonest expiry first, name sorts by the primary name.

Enum values:

urgency

expiry

name

Default: urgency

per_page

integer · min: 1 · max: 100

page

integer · min: 1

List a server's certificates › Responses

Paginated set of ServerCertificate

ServerCertificate[] · required

object · required

GET/servers/{server}/certificates

curl https://server.chief.app/api/v1/servers/:server/certificates \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "certificate_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "server": {
        "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "web-01"
      },
      "fingerprint": "3f6c1a9e0b7d4c2a8e5f1b3d7a9c0e2f4b6d8a1c3e5f7b9d0a2c4e6f8b1d3a5c",
      "serial": "04a1b2c3d4e5f60718293a4b5c6d7e8f9a0b",
      "subject": {
        "cn": "shop.example.com",
        "org": "org"
      },
      "issuer": {
        "cn": "R11",
        "org": "Let's Encrypt"
      },
      "not_before": "not_before",
      "not_after": "not_after",
      "expired": true,
      "days_left": 42,
      "names": [
        "shop.example.com",
        "www.shop.example.com"
      ],
      "key": {
        "type": "ecdsa",
        "bits": 256,
        "curve": "P-256"
      },
      "signature_algorithm": "ECDSA-SHA384",
      "self_signed": true,
      "chain": {
        "complete": true,
        "intermediates": 1
      },
      "paths": [
        "string"
      ],
      "used_by": [
        {
          "kind": "site",
          "ref": "apache/shop.example.com",
          "site_url": "https://server.chief.app/team/acme/sites/01j8q8zk2f4m6n7p9r1s3t5v7x/shop.example.com"
        }
      ],
      "managed_by": {
        "tool": "certbot",
        "name": "shop.example.com",
        "plugin": "dns-domainchief",
        "installer": "apache",
        "ca": "letsencrypt",
        "ca_url": "https://acme-v02.api.letsencrypt.org/directory",
        "renewal": "timer",
        "config": "/etc/letsencrypt/renewal/shop.example.com.conf"
      },
      "issues": [
        {
          "issue": "expiring_unmanaged",
          "severity": "high",
          "label": "Weak key",
          "explanation": "The key is weaker than an RSA 2048-bit or P-256 key, which clients may reject. Issue it again with a stronger key."
        }
      ],
      "severity": "high",
      "first_seen_at": "first_seen_at",
      "url": "https://server.chief.app/team/acme/certificates/01j8q8zk2f4m6n7p9r1s3t5v7x"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

List a server's applications

GET

https://server.chief.app/api/v1

/servers/{server}/applications

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

List a server's applications › path Parameters

server

string · required

List a server's applications › query Parameters

query

string | null · maxLength: 255

Only return applications whose path or site names contain this text.

kind

string | null · enum

Only return applications of this kind.

Enum values:

wordpress

laravel

symfony

composer

node

vulnerable

boolean | null

Only return applications with an open vulnerability in a package they need in production.

malicious

boolean | null

Only return applications with an open malicious package.

end_of_life

boolean | null

Only return applications whose WordPress, Laravel or Symfony release is past its end of life.

outdated

boolean | null

Only return WordPress applications older than WordPress's latest release.

package

string | null · maxLength: 214

Only return applications with this Composer or npm package, or WordPress plugin or theme slug, by its exact name, development dependencies included.

per_page

integer · min: 1 · max: 100

page

integer · min: 1

List a server's applications › Responses

Paginated set of Application

Application[] · required

object · required

GET/servers/{server}/applications

curl https://server.chief.app/api/v1/servers/:server/applications \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "application_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "server": {
        "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "web-01"
      },
      "path": "/home/forge/shop.example.com/current",
      "kind": "wordpress",
      "version": "11.9.2",
      "end_of_life": true,
      "end_of_life_at": "2026-03-12",
      "latest_version": "6.8.3",
      "outdated": true,
      "sites": [
        "shop.example.com",
        "www.shop.example.com"
      ],
      "owner": "forge",
      "lockfiles": [
        "composer.lock",
        "package-lock.json"
      ],
      "packages_count": 214,
      "plugins_count": 15,
      "themes_count": 2,
      "truncated": true,
      "open_vulnerabilities_count": 3,
      "malicious_packages_count": 0,
      "detected_at": "detected_at"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

List a server's package repositories

GET

https://server.chief.app/api/v1

/servers/{server}/repositories

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

List a server's package repositories › path Parameters

server

string · required

List a server's package repositories › Responses

Array of ServerRepository

ServerRepository[] · required

GET/servers/{server}/repositories

curl https://server.chief.app/api/v1/servers/:server/repositories \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "bookworm-security:3f2a9c1e",
      "file": "/etc/apt/sources.list.d/php.list",
      "type": "deb",
      "enabled": true,
      "uris": [
        "https://packages.sury.org/php"
      ],
      "suite": "bookworm",
      "components": [
        "main"
      ],
      "name": "Remi's PHP 8.3 RPM repository for Enterprise Linux 9",
      "signing": {
        "signed_by": "/usr/share/keyrings/deb.sury.org-php.gpg",
        "trusted": true,
        "gpgcheck": true
      },
      "transport": "https",
      "packages": 42,
      "vendor": {
        "slug": "sury",
        "label": "Sury",
        "kind": "distro"
      },
      "issues": [
        {
          "issue": "insecure_trusted",
          "informational": true,
          "label": "Trusted without signature",
          "explanation": "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."
        }
      ],
      "first_seen_at": "first_seen_at"
    }
  ]
}

json

application/json

List a server's vulnerabilities

GET

https://server.chief.app/api/v1

/servers/{server}/vulnerabilities

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

List a server's vulnerabilities › path Parameters

server

string · required

List a server's vulnerabilities › query Parameters

cve

string | null · maxLength: 64 · pattern: ^[A-Za-z][A-Za-z0-9]…

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.

severity

string | null · enum

Only return vulnerabilities of this severity or worse. Unknown only matches unrated vulnerabilities.

Enum values:

critical

high

medium

low

negligible

unknown

fix_status

string | null · enum

Only return vulnerabilities with this fix status.

Enum values:

available

reboot

released

none

known_exploited

boolean | null

Only return vulnerabilities CISA lists as known exploited (true), or those it does not list (false).

public_exploit

boolean | null

Only return vulnerabilities Metasploit, Nuclei or Exploit-DB has a public exploit of (true), or those without one (false).

min_epss

number | null · min: 0 · max: 1

Only return vulnerabilities with at least this EPSS score, the probability of exploitation activity in the next 30 days.

package

string | null · maxLength: 255

Only return vulnerabilities of this source package, or of the source of this binary package.

status

string | null · enum

open for current vulnerabilities, resolved for vulnerabilities that were fixed or no longer apply, all for both.

Enum values:

open

resolved

all

Default: open

per_page

integer · min: 1 · max: 100

page

integer · min: 1

List a server's vulnerabilities › Responses

Array of ServerVulnerability

ServerVulnerability[] · required

GET/servers/{server}/vulnerabilities

curl https://server.chief.app/api/v1/servers/:server/vulnerabilities \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "server": {
        "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "web-01"
      },
      "vulnerability_id": "CVE-2023-5363",
      "advisory_id": "DEBIAN-CVE-2023-5363",
      "advisory_ids": [
        "DEBIAN-CVE-2023-5363",
        "DSA-5532-1"
      ],
      "summary": "openssl - security update",
      "package": "openssl",
      "binary_package": "libssl3",
      "installed_version": "3.0.11-1~deb12u1",
      "fixed_version": "3.0.11-1~deb12u2",
      "fixed_release": "debian:12",
      "requires_subscription": true,
      "fix_status": "available",
      "severity": "critical",
      "cvss_score": 7.5,
      "known_exploited": true,
      "known_exploited_at": "2026-10-27",
      "epss_score": 0.04753,
      "epss_percentile": 0.91849,
      "public_exploit": true,
      "metasploit_module": "exploit/linux/http/magento_xxe_to_glibc_buf_overflow",
      "nuclei_template": "http/cves/2021/CVE-2021-44228.yaml",
      "exploit_db_id": 50973,
      "first_seen_at": "first_seen_at",
      "resolved_at": "resolved_at",
      "resolved_version": "3.0.11-1~deb12u2"
    }
  ]
}

json

application/json

List a server's changes

GET

https://server.chief.app/api/v1

/servers/{server}/changes

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

List a server's changes › path Parameters

server

string · required

List a server's changes › query Parameters

dataset

string | null · enum

Only return changes of a dataset.

Enum values:

system

hardware

network

resolvers

cloud

packages

vhosts

certificates

kind

string | null · enum

Only return changes of a kind.

Enum values:

changed

added

removed

since

string | null · date-time

Only return changes detected at or after this ISO 8601 date or timestamp.

per_page

integer · min: 1 · max: 100

page

integer · min: 1

List a server's changes › Responses

Paginated set of ServerChange

ServerChange[] · required

object · required

GET/servers/{server}/changes

curl https://server.chief.app/api/v1/servers/:server/changes \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "change_01jb9a2c3d4e5f6g7h8j9k0m1n",
      "dataset": "packages",
      "kind": "changed",
      "subject": "php8.2-fpm",
      "label": "Package php8.2-fpm",
      "old": {},
      "new": {},
      "detected_at": "detected_at"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

Show a server's inventory dataset

GET

https://server.chief.app/api/v1

/servers/{server}/inventory/{dataset}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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).

Show a server's inventory dataset › path Parameters

server

string · required

dataset

string · required

Show a server's inventory dataset › Responses

ServerInventory

ServerInventory · required

Replace a server's tags

PUT

https://server.chief.app/api/v1

/servers/{server}/tags

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Replace a server's tags › path Parameters

server

string · required

Replace a server's tags › Request Body

ReplaceServerTagsRequest

tags

string[] · maxItems: 50 · unique · required

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

Example: ["production","web"]

Replace a server's tags › Responses

Server

Server · required

PUT/servers/{server}/tags

curl https://server.chief.app/api/v1/servers/:server/tags \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "tags": [
    "production",
    "web"
  ]
}'

Example Request Body

{
  "tags": [
    "production",
    "web"
  ]
}

json

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "web-01",
    "hostname": "web-01.example.com",
    "owner_team": {
      "slug": "acme",
      "name": "Acme Inc"
    },
    "access": "owner",
    "tags": [
      {
        "id": "tag_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "production",
        "color": "zinc"
      }
    ],
    "metadata": {
      "key": "string"
    },
    "status": "pending",
    "agent_version": "1.0.0",
    "agent": {
      "version": "1.0.0",
      "update_available": true,
      "auto_updates": {
        "enabled": true,
        "is_default": true
      },
      "capability": {
        "available": true,
        "reason": "installed from a tarball"
      },
      "reboot": {
        "available": true,
        "reason": "running in a Docker container"
      },
      "upgrade_packages": {
        "available": true,
        "reason": "the root helper does not answer"
      },
      "disabled_actions": [
        "reboot"
      ]
    },
    "last_contact_at": "last_contact_at",
    "fqdn": "web-01.example.com",
    "os_family": "debian",
    "os_id": "ubuntu",
    "os_name": "Ubuntu",
    "os_version": "24.04.1",
    "os_codename": "noble",
    "kernel_release": "6.8.0-45-generic",
    "arch": "amd64",
    "virtualization": "guest/kvm",
    "boot_time": "boot_time",
    "cpu_model": "AMD EPYC 7763 64-Core Processor",
    "cpu_cores": 4,
    "cpu_threads": 8,
    "memory_bytes": 17179869184,
    "swap_bytes": 0,
    "disk_bytes": 0,
    "storage_health": "healthy",
    "storage_unhealthy_since": "storage_unhealthy_since",
    "public_ipv4": "203.0.113.10",
    "public_ipv6": "2001:db8::10",
    "observed_ip": "198.51.100.7",
    "nameservers": [
      "string"
    ],
    "addresses": [
      {
        "interface": "eth0",
        "address": "203.0.113.10",
        "prefix": 24,
        "family": 4,
        "scope": "public"
      }
    ],
    "is_os_eol": true,
    "os_eol_at": "os_eol_at",
    "pending_updates_count": 12,
    "security_updates_count": 3,
    "reboot_required": true,
    "updates_checked_at": "updates_checked_at",
    "package_metadata_refresh": {
      "enabled": true,
      "interval": 21600,
      "is_default": true
    },
    "software": [
      {
        "product": "php",
        "version": "7.4.33",
        "package_version": "7.4.33-1+ubuntu16.04.1+deb.sury.org+1",
        "manager": "dpkg",
        "major": 7,
        "minor": 4,
        "patch": 33,
        "package": "php7.4-fpm",
        "source": "package",
        "is_eol": true,
        "eol_at": "eol_at"
      }
    ],
    "provider": "hetzner",
    "city": "Falkenstein",
    "country": "DE",
    "continent": "EU",
    "location_source": "agent",
    "cloud_region": "fsn1",
    "cloud_zone": "fsn1-dc14",
    "instance_type": "m6i.large",
    "asn": 24940,
    "asn_org": "Hetzner Online GmbH",
    "location_override": {
      "provider": "hetzner",
      "city": "Falkenstein",
      "country": "DE",
      "continent": "EU"
    },
    "vhosts_count": 12,
    "certificates_count": 4,
    "certificate_issues_count": 1,
    "repositories": {
      "count": 8,
      "third_party_count": 3,
      "issues_count": 1,
      "orphaned_packages_count": 2,
      "not_covered_packages_count": 4,
      "vendors": [
        {
          "slug": "slug",
          "label": "label",
          "kind": "distro",
          "repositories": 0,
          "issues": [
            "insecure_trusted"
          ]
        }
      ]
    },
    "vulnerabilities": {
      "release": "debian:12",
      "critical": 2,
      "high": 5,
      "medium": 12,
      "low": 20,
      "negligible": 30,
      "unknown": 1,
      "total": 70,
      "fixable": 9,
      "reboot": 1,
      "subscription": 3,
      "released": 0,
      "unfixed": 57,
      "checked_at": "checked_at"
    },
    "enrollment": {
      "token": "scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "install_command": "curl -fsSL https://pkg.server.chief.app/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "expires_at": "expires_at"
    },
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Attach or detach server tags

PATCH

https://server.chief.app/api/v1

/servers/{server}/tags

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Attach or detach server tags › path Parameters

server

string · required

Attach or detach server tags › Request Body

UpdateServerTagsRequest

attach

string[] · maxItems: 50 · unique

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

Example: ["production"]

detach

string[] · maxItems: 50 · unique

Tags to detach, by formatted ID or by name.

Example: ["staging"]

Attach or detach server tags › Responses

Server

Server · required

PATCH/servers/{server}/tags

curl https://server.chief.app/api/v1/servers/:server/tags \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "attach": [
    "production"
  ],
  "detach": [
    "staging"
  ]
}'

Example Request Body

{
  "attach": [
    "production"
  ],
  "detach": [
    "staging"
  ]
}

json

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "web-01",
    "hostname": "web-01.example.com",
    "owner_team": {
      "slug": "acme",
      "name": "Acme Inc"
    },
    "access": "owner",
    "tags": [
      {
        "id": "tag_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "production",
        "color": "zinc"
      }
    ],
    "metadata": {
      "key": "string"
    },
    "status": "pending",
    "agent_version": "1.0.0",
    "agent": {
      "version": "1.0.0",
      "update_available": true,
      "auto_updates": {
        "enabled": true,
        "is_default": true
      },
      "capability": {
        "available": true,
        "reason": "installed from a tarball"
      },
      "reboot": {
        "available": true,
        "reason": "running in a Docker container"
      },
      "upgrade_packages": {
        "available": true,
        "reason": "the root helper does not answer"
      },
      "disabled_actions": [
        "reboot"
      ]
    },
    "last_contact_at": "last_contact_at",
    "fqdn": "web-01.example.com",
    "os_family": "debian",
    "os_id": "ubuntu",
    "os_name": "Ubuntu",
    "os_version": "24.04.1",
    "os_codename": "noble",
    "kernel_release": "6.8.0-45-generic",
    "arch": "amd64",
    "virtualization": "guest/kvm",
    "boot_time": "boot_time",
    "cpu_model": "AMD EPYC 7763 64-Core Processor",
    "cpu_cores": 4,
    "cpu_threads": 8,
    "memory_bytes": 17179869184,
    "swap_bytes": 0,
    "disk_bytes": 0,
    "storage_health": "healthy",
    "storage_unhealthy_since": "storage_unhealthy_since",
    "public_ipv4": "203.0.113.10",
    "public_ipv6": "2001:db8::10",
    "observed_ip": "198.51.100.7",
    "nameservers": [
      "string"
    ],
    "addresses": [
      {
        "interface": "eth0",
        "address": "203.0.113.10",
        "prefix": 24,
        "family": 4,
        "scope": "public"
      }
    ],
    "is_os_eol": true,
    "os_eol_at": "os_eol_at",
    "pending_updates_count": 12,
    "security_updates_count": 3,
    "reboot_required": true,
    "updates_checked_at": "updates_checked_at",
    "package_metadata_refresh": {
      "enabled": true,
      "interval": 21600,
      "is_default": true
    },
    "software": [
      {
        "product": "php",
        "version": "7.4.33",
        "package_version": "7.4.33-1+ubuntu16.04.1+deb.sury.org+1",
        "manager": "dpkg",
        "major": 7,
        "minor": 4,
        "patch": 33,
        "package": "php7.4-fpm",
        "source": "package",
        "is_eol": true,
        "eol_at": "eol_at"
      }
    ],
    "provider": "hetzner",
    "city": "Falkenstein",
    "country": "DE",
    "continent": "EU",
    "location_source": "agent",
    "cloud_region": "fsn1",
    "cloud_zone": "fsn1-dc14",
    "instance_type": "m6i.large",
    "asn": 24940,
    "asn_org": "Hetzner Online GmbH",
    "location_override": {
      "provider": "hetzner",
      "city": "Falkenstein",
      "country": "DE",
      "continent": "EU"
    },
    "vhosts_count": 12,
    "certificates_count": 4,
    "certificate_issues_count": 1,
    "repositories": {
      "count": 8,
      "third_party_count": 3,
      "issues_count": 1,
      "orphaned_packages_count": 2,
      "not_covered_packages_count": 4,
      "vendors": [
        {
          "slug": "slug",
          "label": "label",
          "kind": "distro",
          "repositories": 0,
          "issues": [
            "insecure_trusted"
          ]
        }
      ]
    },
    "vulnerabilities": {
      "release": "debian:12",
      "critical": 2,
      "high": 5,
      "medium": 12,
      "low": 20,
      "negligible": 30,
      "unknown": 1,
      "total": 70,
      "fixable": 9,
      "reboot": 1,
      "subscription": 3,
      "released": 0,
      "unfixed": 57,
      "checked_at": "checked_at"
    },
    "enrollment": {
      "token": "scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "install_command": "curl -fsSL https://pkg.server.chief.app/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "expires_at": "expires_at"
    },
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

List install commands

GET

https://server.chief.app/api/v1

/install-commands

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the team's install commands that can still add servers, the newest first. Their tokens are never shown again.

List install commands › query Parameters

query

string | null · maxLength: 255

Search results by name.

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

List install commands › Responses

Array of InstallCommand

InstallCommand[] · required

GET/install-commands

curl https://server.chief.app/api/v1/install-commands \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "install_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "token": "scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "install_command": "curl -fsSL https://pkg.server.chief.app/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "status": "active",
      "description": "Web servers in Frankfurt",
      "single_use": true,
      "servers_added": 2,
      "tags": [
        {
          "id": "tag_01j8q8zk2f4m6n7p9r1s3t5v7x",
          "name": "production",
          "color": "zinc"
        }
      ],
      "expires_at": "expires_at",
      "last_used_at": "last_used_at",
      "revoked_at": "revoked_at",
      "created_at": "created_at"
    }
  ]
}

json

application/json

Create an install command

POST

https://server.chief.app/api/v1

/install-commands

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Create an install command › Request Body

CreateInstallCommandRequest

single_use

boolean

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

Default: true

valid_for_hours

integer · min: 1 · max: 24

Hours the command can add servers, at most 24.

Default: 1

description

string | null · maxLength: 255

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

Example: Web servers in Frankfurt

tags

string[] · maxItems: 50 · unique

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

Example: ["production","tag_01j8q8zk2f4m6n7p9r1s3t5v7x"]

Create an install command › Responses

The install command was created.

InstallCommand · required

POST/install-commands

curl https://server.chief.app/api/v1/install-commands \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "single_use": true,
  "valid_for_hours": 1,
  "description": "Web servers in Frankfurt",
  "tags": [
    "production",
    "tag_01j8q8zk2f4m6n7p9r1s3t5v7x"
  ]
}'

Example Request Body

{
  "single_use": true,
  "valid_for_hours": 1,
  "description": "Web servers in Frankfurt",
  "tags": [
    "production",
    "tag_01j8q8zk2f4m6n7p9r1s3t5v7x"
  ]
}

json

Example Responses

{
  "data": {
    "id": "install_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "token": "scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
    "install_command": "curl -fsSL https://pkg.server.chief.app/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
    "status": "active",
    "description": "Web servers in Frankfurt",
    "single_use": true,
    "servers_added": 2,
    "tags": [
      {
        "id": "tag_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "production",
        "color": "zinc"
      }
    ],
    "expires_at": "expires_at",
    "last_used_at": "last_used_at",
    "revoked_at": "revoked_at",
    "created_at": "created_at"
  }
}

json

application/json

Revoke an install command

POST

https://server.chief.app/api/v1

/install-commands/{installCommand}/revoke

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Stop an install command from adding servers. Servers it already added keep working.

Revoke an install command › path Parameters

installCommand

string · required

Revoke an install command › Responses

InstallCommand

InstallCommand · required

POST/install-commands/{installCommand}/revoke

curl https://server.chief.app/api/v1/install-commands/:installCommand/revoke \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "install_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "token": "scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
    "install_command": "curl -fsSL https://pkg.server.chief.app/install.sh | sudo bash && sudo serverchief setup scenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
    "status": "active",
    "description": "Web servers in Frankfurt",
    "single_use": true,
    "servers_added": 2,
    "tags": [
      {
        "id": "tag_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "production",
        "color": "zinc"
      }
    ],
    "expires_at": "expires_at",
    "last_used_at": "last_used_at",
    "revoked_at": "revoked_at",
    "created_at": "created_at"
  }
}

json

application/json

Packages