Servers

Download schema

Endpoints for the servers of the team. Each server runs the Backup Chief agent, which runs its backup jobs and reports their results.

List servers

GET

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

/servers

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the team's servers by name.

List servers › 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

status

string | null · enum

Only return servers in this state: attention for servers whose agent is offline or rejected its configuration, connected, offline, pending or revoked.

Enum values:

attention

connected

offline

pending

revoked

List servers › Responses

Paginated set of Server

Server[] · required

object · required

GET/servers

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

Example Responses

{
  "data": [
    {
      "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "Web server",
      "hostname": "web-1.example.com",
      "status": "pending",
      "connected": true,
      "platform": "linux/amd64",
      "agent": {
        "version": "1.4.2",
        "auto_updates": true,
        "auto_updates_override": true,
        "upgrade_required": true,
        "update": {
          "target_version": "1.5.0",
          "status": "pending",
          "requested_at": "requested_at",
          "completed_at": "completed_at"
        }
      },
      "active_jobs_count": 0,
      "jobs_count": 0,
      "last_contact_at": "last_contact_at",
      "enrolled_at": "enrolled_at",
      "revoked_at": "revoked_at",
      "created_at": "created_at",
      "enrollment": {
        "token": "bcenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
        "setup_command": "setup_command",
        "expires_at": "expires_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://backup.chief.app/api/v1

/servers

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Add a pending server to the team. The response includes a one-time enrollment token, valid for one hour, and the setup 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

Display name of the server.

Example: Web server

agent_auto_updates

boolean | null

Whether the server installs new agent releases automatically, null to follow the team setting.

Create a server › Responses

The server was created.

Server · required

POST/servers

curl https://backup.chief.app/api/v1/servers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Web server",
  "agent_auto_updates": true
}'

Example Request Body

{
  "name": "Web server",
  "agent_auto_updates": true
}

json

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "Web server",
    "hostname": "web-1.example.com",
    "status": "pending",
    "connected": true,
    "platform": "linux/amd64",
    "agent": {
      "version": "1.4.2",
      "auto_updates": true,
      "auto_updates_override": true,
      "upgrade_required": true,
      "update": {
        "target_version": "1.5.0",
        "status": "pending",
        "requested_at": "requested_at",
        "completed_at": "completed_at"
      }
    },
    "active_jobs_count": 0,
    "jobs_count": 0,
    "last_contact_at": "last_contact_at",
    "enrolled_at": "enrolled_at",
    "revoked_at": "revoked_at",
    "created_at": "created_at",
    "enrollment": {
      "token": "bcenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "setup_command": "setup_command",
      "expires_at": "expires_at"
    }
  }
}

json

application/json

Get a server

GET

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

/servers/{server}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Get one of the team's servers with its agent status, version and job counts.

Get a server › path Parameters

server

string · required

Get a server › Responses

Server

Server · required

GET/servers/{server}

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

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "Web server",
    "hostname": "web-1.example.com",
    "status": "pending",
    "connected": true,
    "platform": "linux/amd64",
    "agent": {
      "version": "1.4.2",
      "auto_updates": true,
      "auto_updates_override": true,
      "upgrade_required": true,
      "update": {
        "target_version": "1.5.0",
        "status": "pending",
        "requested_at": "requested_at",
        "completed_at": "completed_at"
      }
    },
    "active_jobs_count": 0,
    "jobs_count": 0,
    "last_contact_at": "last_contact_at",
    "enrolled_at": "enrolled_at",
    "revoked_at": "revoked_at",
    "created_at": "created_at",
    "enrollment": {
      "token": "bcenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "setup_command": "setup_command",
      "expires_at": "expires_at"
    }
  }
}

json

application/json

Update a server

PATCH

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

/servers/{server}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Rename a server or change whether it installs new agent releases automatically. Fields left out keep their value.

Update a server › path Parameters

server

string · required

Update a server › Request Body

SaveServerRequest

name

string · maxLength: 255 · required

Display name of the server.

Example: Web server

agent_auto_updates

boolean | null

Whether the server installs new agent releases automatically, null to follow the team setting.

Update a server › Responses

Server

Server · required

PATCH/servers/{server}

curl https://backup.chief.app/api/v1/servers/:server \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Web server",
  "agent_auto_updates": true
}'

Example Request Body

{
  "name": "Web server",
  "agent_auto_updates": true
}

json

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "Web server",
    "hostname": "web-1.example.com",
    "status": "pending",
    "connected": true,
    "platform": "linux/amd64",
    "agent": {
      "version": "1.4.2",
      "auto_updates": true,
      "auto_updates_override": true,
      "upgrade_required": true,
      "update": {
        "target_version": "1.5.0",
        "status": "pending",
        "requested_at": "requested_at",
        "completed_at": "completed_at"
      }
    },
    "active_jobs_count": 0,
    "jobs_count": 0,
    "last_contact_at": "last_contact_at",
    "enrolled_at": "enrolled_at",
    "revoked_at": "revoked_at",
    "created_at": "created_at",
    "enrollment": {
      "token": "bcenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "setup_command": "setup_command",
      "expires_at": "expires_at"
    }
  }
}

json

application/json

Delete a server

DELETE

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

/servers/{server}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Delete a pending server that never enrolled. Revoke an enrolled server instead; its history is kept.

Delete a server › path Parameters

server

string · required

Delete a server › Responses

The server was deleted.

string

Revoke a server

POST

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

/servers/{server}/revoke

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Revoke the server's agent credential and cancel its pending work. Backup jobs, runs and snapshots are kept. Revocation cannot reach an offline or compromised machine: also revoke the storage credentials it used. Revoking a revoked server changes nothing.

Revoke a server › path Parameters

server

string · required

Revoke a server › Responses

Server

Server · required

POST/servers/{server}/revoke

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

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "Web server",
    "hostname": "web-1.example.com",
    "status": "pending",
    "connected": true,
    "platform": "linux/amd64",
    "agent": {
      "version": "1.4.2",
      "auto_updates": true,
      "auto_updates_override": true,
      "upgrade_required": true,
      "update": {
        "target_version": "1.5.0",
        "status": "pending",
        "requested_at": "requested_at",
        "completed_at": "completed_at"
      }
    },
    "active_jobs_count": 0,
    "jobs_count": 0,
    "last_contact_at": "last_contact_at",
    "enrolled_at": "enrolled_at",
    "revoked_at": "revoked_at",
    "created_at": "created_at",
    "enrollment": {
      "token": "bcenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "setup_command": "setup_command",
      "expires_at": "expires_at"
    }
  }
}

json

application/json

Issue an enrollment token

POST

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

/servers/{server}/enrollment-token

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Issue a new one-time enrollment token, valid for one hour, with the setup command to run on the server. Earlier unused tokens stop working. For a pending server the token enrolls its first agent. For an enrolled or revoked server it sets the server up again: the server becomes pending, its current agent is disconnected and its running work is cancelled.

Issue an enrollment token › path Parameters

server

string · required

Issue an enrollment token › Responses

The token was issued.

Server · required

POST/servers/{server}/enrollment-token

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

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "Web server",
    "hostname": "web-1.example.com",
    "status": "pending",
    "connected": true,
    "platform": "linux/amd64",
    "agent": {
      "version": "1.4.2",
      "auto_updates": true,
      "auto_updates_override": true,
      "upgrade_required": true,
      "update": {
        "target_version": "1.5.0",
        "status": "pending",
        "requested_at": "requested_at",
        "completed_at": "completed_at"
      }
    },
    "active_jobs_count": 0,
    "jobs_count": 0,
    "last_contact_at": "last_contact_at",
    "enrolled_at": "enrolled_at",
    "revoked_at": "revoked_at",
    "created_at": "created_at",
    "enrollment": {
      "token": "bcenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "setup_command": "setup_command",
      "expires_at": "expires_at"
    }
  }
}

json

application/json

Update the agent

POST

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

/servers/{server}/agent-update

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Ask the server's agent to install the latest agent release once its current work reaches a safe stopping point. The agent must be connected and support remote updates. When an update is already scheduled, that update is kept.

Update the agent › path Parameters

server

string · required

Update the agent › Responses

Server

Server · required

POST/servers/{server}/agent-update

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

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "Web server",
    "hostname": "web-1.example.com",
    "status": "pending",
    "connected": true,
    "platform": "linux/amd64",
    "agent": {
      "version": "1.4.2",
      "auto_updates": true,
      "auto_updates_override": true,
      "upgrade_required": true,
      "update": {
        "target_version": "1.5.0",
        "status": "pending",
        "requested_at": "requested_at",
        "completed_at": "completed_at"
      }
    },
    "active_jobs_count": 0,
    "jobs_count": 0,
    "last_contact_at": "last_contact_at",
    "enrolled_at": "enrolled_at",
    "revoked_at": "revoked_at",
    "created_at": "created_at",
    "enrollment": {
      "token": "bcenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE",
      "setup_command": "setup_command",
      "expires_at": "expires_at"
    }
  }
}

json

application/json

Team Storage destinations