PBS REST API: backup automation and integration · Proxmox VE

PBS has its own REST API, on port 8007, in the same style as PVE’s. Use it to integrate backup operations into your own tooling, report on datastore health, and drive maintenance from a scheduler you control.

Two things about it are different enough from PVE to be worth learning before you write anything, and both are places where copied examples routinely fail.

Authentication: the header is not the PVE one

Create the token on the PBS host. The command is generate-token, and the secret it returns is displayed once.

Configuration changecreate a PBS API token— Creates the user and generates a token. The documentation is explicit that the displayed secret value needs to be saved, since it cannot be displayed again after generating the API token. Grant it permissions separately with acl update.

proxmox-backup-manager user create automation@pbs --comment "reporting pipeline"

proxmox-backup-manager user generate-token automation@pbs reporting

proxmox-backup-manager acl update /datastore/main DatastoreAudit \
--auth-id 'automation@pbs!reporting'

Read-only / Safewhat generate-token returns— Illustrative, with the secret redacted. The tokenid combines the user and the token name with an exclamation mark; the value is the secret and this is the only time you will see it.

# proxmox-backup-manager user generate-token automation@pbs reporting

Result: {
"tokenid": "automation@pbs!reporting",
"value": "REDACTED-SECRET-VALUE"
}

Illustrative output

PBS separates the secret with a colon; PVE uses an equals sign

This is the first thing that breaks when a PVE script is adapted for PBS, and the failure is a bare 401 with no hint about the cause.

The PBS documentation states it precisely: the token “is passed from the client to the server by setting the Authorization HTTP header with method PBSAPIToken to the value TOKENID:TOKENSECRET”.

	Format
PVE	`Authorization: PVEAPIToken=USER@REALM!TOKENID=SECRET`
PBS	`Authorization: PBSAPIToken USER@REALM!TOKENID:SECRET`

Two differences: the separator before the secret is a colon rather than an equals sign, and the scheme is followed by a space in the standard HTTP Authorization: <scheme> <credentials> shape.

Both products return 401 for a malformed header exactly as they do for a wrong secret, so the symptom points at the credential rather than at the syntax. If a freshly generated PBS token gives you 401 on the first call, check the separator before you regenerate anything.

Read-only / Safea first authenticated call— Read-only. Keep the secret in an environment variable rather than on the command line, where it would land in shell history and in ps. Use --cacert against the PBS fingerprint or a proper certificate rather than -k.

PBS=https://pbs.example.com:8007/api2/json
PBS_TOKEN='automation@pbs!reporting:REPLACE_ME'

curl -sS -H "Authorization: PBSAPIToken $PBS_TOKEN" "$PBS/status" | jq '.data'

The path prefix nearly every example gets wrong

Datastore operations do not live at /api2/json/datastore/{store}. They live under /api2/json/admin/datastore/{store}, and the shorter path — which appears in a great deal of circulating example code — returns a 404 that reads like the datastore does not exist.

Operation	Method and path
List datastores	`GET /admin/datastore`
Datastore usage and GC status	`GET /admin/datastore/{store}/status`
List snapshots	`GET /admin/datastore/{store}/snapshots`
List backup groups	`GET /admin/datastore/{store}/groups`
Delete one snapshot	`DELETE /admin/datastore/{store}/snapshots`
Start garbage collection	`POST /admin/datastore/{store}/gc`
Read GC status and schedule	`GET /admin/datastore/{store}/gc`
Start verification	`POST /admin/datastore/{store}/verify`
Prune a group by retention	`POST /admin/datastore/{store}/prune`
Usage across all datastores	`GET /status/datastore-usage`
Configured (not runtime) datastores	`GET /config/datastore`

The /config/ versus /admin/ split is the same idea as elsewhere in Proxmox: /config/ is what is defined, /admin/ is what is happening.

Read-only / Safelist datastores and inspect one— Read-only. The status endpoint returns total, used and avail in bytes plus a gc-status object, which is the single most useful call for monitoring.

PBS=https://pbs.example.com:8007/api2/json
H="Authorization: PBSAPIToken $PBS_TOKEN"

curl -sS -H "$H" "$PBS/admin/datastore" | jq -r '.data[].store'

STORE=main
curl -sS -H "$H" "$PBS/admin/datastore/$STORE/status" | jq '.data | {total, used, avail}'

Read-only / Safewhat is in the datastore, and did it verify?— Read-only. backup-time is a Unix timestamp. The verification object carries the state of the last verify for that snapshot, which is the field that tells you whether a backup is known-good rather than merely present.

PBS=https://pbs.example.com:8007/api2/json
H="Authorization: PBSAPIToken $PBS_TOKEN"
STORE=main

curl -sS -H "$H" "$PBS/admin/datastore/$STORE/snapshots" \
| jq -r '.data[] | [(."backup-type"), (."backup-id"), (."backup-time"|todate), (.verification.state // "unverified"), .size] | @tsv' \
| sort -k3

Read-only / Safesnapshots with their verification state— Illustrative. The unverified row is the finding: that backup exists and nothing has confirmed it is readable. A backup whose verification state is not 'ok' is a hypothesis, not a recovery point.

# (the command above)

vm	100	2026-08-11T02:00:07Z	ok	  536870912000
vm	101	2026-08-11T02:14:33Z	ok	   53687091200
vm	141	2026-08-11T02:31:52Z	failed	  214748364800
ct	205	2026-08-11T02:40:11Z	unverified	 2147483648

Illustrative output

PBS cannot be asked to take a backup

This is the second structural difference, and it invalidates a whole category of scripts people try to write.

Backups are pushed to PBS, never pulled by it. The client — either proxmox-backup-client on a standalone host, or PVE’s vzdump for guests — reads the data, chunks it, and uploads it. PBS is a destination. There is no endpoint on PBS that means “go and back up VM 100”, because PBS has no access to VM 100 and no way to quiesce it.

So a request for an on-demand backup goes to PVE, not to PBS:

Service impact possiblerequest a backup — from PVE, targeting the PBS storage— Runs vzdump on the PVE node, writing to the PBS-backed storage. This is a state change on PVE and returns a UPID; poll it to completion rather than assuming success. bwlimit is in KiB/s and stops an ad-hoc backup saturating shared storage.

PVE=https://pve-01.example.com:8006/api2/json
NODE=pve-01
VMID=100

UPID=$(curl -sS -X POST \
-H "Authorization: PVEAPIToken $PVE_TOKEN" \
--data-urlencode "vmid=$VMID" \
--data-urlencode "storage=backup-pbs" \
--data-urlencode "mode=snapshot" \
--data-urlencode "bwlimit=102400" \
--data-urlencode "notes-template=pre-migration {{guestname}}" \
"$PVE/nodes/$NODE/vzdump" | jq -r .data)

echo "task: $UPID"

Note that the PVE token in that call uses PVE’s = separator, and the PBS calls above use PBS’s : — a script that talks to both needs two differently-shaped headers, which is worth a comment in the code.

Maintenance operations, and following them

Garbage collection, verification and pruning are all long-running and all return a UPID.

Service impact possiblestart garbage collection and follow it— GC reclaims space from chunks no snapshot references. It is I/O heavy and can run for hours on a large datastore. The GET on the same path reports last-run-state, next-run and the current upid without starting anything.

PBS=https://pbs.example.com:8007/api2/json
H="Authorization: PBSAPIToken $PBS_TOKEN"
STORE=main

curl -sS -H "$H" "$PBS/admin/datastore/$STORE/gc" \
| jq '.data | {"last-run-state", "next-run", "removed-bytes", "pending-bytes"}'

UPID=$(curl -sS -X POST -H "$H" "$PBS/admin/datastore/$STORE/gc" | jq -r .data)
echo "gc task: $UPID"

Service impact possibleverify a datastore, skipping what is already known good— Reads every chunk and checks it against its digest, which is the only thing that proves a backup is restorable. ignore-verified with outdated-after avoids re-reading snapshots verified recently, which is what makes a nightly verify job affordable.

PBS=https://pbs.example.com:8007/api2/json
H="Authorization: PBSAPIToken $PBS_TOKEN"
STORE=main

curl -sS -X POST -H "$H" \
--data-urlencode "ignore-verified=1" \
--data-urlencode "outdated-after=30" \
"$PBS/admin/datastore/$STORE/verify" | jq -r .data

Data-loss riskprune by retention — always dry-run first— Prune permanently removes backups that fall outside the retention policy. dry-run=1 returns exactly which snapshots would be kept and removed without touching anything. Run it, read it, and only then run it again without dry-run.

PBS=https://pbs.example.com:8007/api2/json
H="Authorization: PBSAPIToken $PBS_TOKEN"
STORE=main

curl -sS -X POST -H "$H" \
--data-urlencode "backup-type=vm" \
--data-urlencode "backup-id=100" \
--data-urlencode "keep-daily=7" \
--data-urlencode "keep-weekly=4" \
--data-urlencode "keep-monthly=6" \
--data-urlencode "dry-run=1" \
"$PBS/admin/datastore/$STORE/prune" \
| jq -r '.data[] | [(."backup-time"|todate), (if .keep then "KEEP" else "REMOVE" end)] | @tsv'

Reporting: PBS already computes the number you want

Read-only / Safeusage across every datastore, with a projected full date— Read-only. /status/datastore-usage returns total, used and avail per datastore plus estimated-full-date, which PBS derives from its own usage history. That is the figure a capacity report should lead with.

PBS=https://pbs.example.com:8007/api2/json
H="Authorization: PBSAPIToken $PBS_TOKEN"

curl -sS -H "$H" "$PBS/status/datastore-usage" | jq -r '
.data[] | [ .store,
            ((.used / .total * 100) | floor | tostring + "%"),
            (if ."estimated-full-date" then (."estimated-full-date"|todate) else "no estimate" end)
          ] | @tsv'

Read-only / Safethe capacity report, in one call— Illustrative. estimated-full-date is derived by PBS from its own usage history, so it accounts for the actual deduplication and growth of your data rather than a straight-line extrapolation you would have to compute yourself.

# (the command above)

main	61%	2027-03-14T00:00:00Z
offsite	88%	2026-10-02T00:00:00Z
archive	12%	no estimate

Illustrative output

For time-series work, GET /status/metrics returns the same underlying data in a form intended for a metrics collector, which is a better base for a Grafana dashboard than polling and reshaping the admin endpoints yourself.

Under the hood

Why PBS is a destination rather than an orchestrator, and what follows from that.

A PBS backup is created by the client reading the source data, splitting it into content-addressed chunks, hashing each one, asking the server which chunks it already has, and uploading only the ones it does not. The server stores chunks in a shared pool and stores an index per snapshot that lists the chunks making it up.

That design decision — the client does the chunking — is what produces most of PBS’s observable behaviour.

Deduplication is global to the datastore and free at upload time. Twenty guests running the same base image upload the common chunks once, because the second client asks about a hash the server already holds and is told to skip it. This is also why a datastore’s used figure bears little relation to the sum of the snapshot sizes reported per backup: each snapshot reports its logical size, while the datastore holds one copy of each unique chunk.

The server cannot initiate anything, because it has no access to the source. It never sees a filesystem, a block device or a running guest. It sees chunk uploads. There is therefore nothing for a “start backup” endpoint to do, which is why none exists and why an on-demand backup request must go to PVE.

Garbage collection is a two-phase mark and sweep, and this explains its timing. Phase one walks every index and touches the atime of every chunk it references; phase two removes chunks whose atime was not updated and which are older than a safety cutoff. The cutoff exists because a backup in progress uploads chunks before writing the index that references them, so a chunk can be legitimately unreferenced for the duration of a running backup. That is why GC does not immediately reclaim space after a prune, why pending-bytes appears in the GC status alongside removed-bytes, and why running GC concurrently with heavy backup activity is inadvisable rather than merely slow.

Verification is the only operation that reads the data back. Every other operation trusts the index. Verification re-reads chunks and checks each against its digest, which is what detects bit rot in the datastore’s own storage — and it is the reason a verification state of ok means something quite different from a backup task that exited zero.

What happens if you script against the PBS API and it silently returns nothing?

Two causes account for nearly all of it, and they present identically: an HTTP 200 with an empty data array, or a 404 that reads like the resource is missing.

The path prefix. GET /api2/json/datastore/main/snapshots is not an error in any obvious way — it is simply not the endpoint, and PBS answers 404. Because the datastore is named in the URL, the natural reading is that the datastore does not exist, so the investigation goes to the PBS configuration rather than to the path. The correct prefix is /api2/json/admin/datastore/main/snapshots. Confirm by calling GET /admin/datastore first: if that lists your store, the datastore is fine and the path was wrong.

The token’s permissions. This is the subtler one, and the reason it is worth knowing separately. A token with no ACL on a datastore does not get a 403 from the list endpoints — it gets a 200 with an empty array, because from that token’s point of view there are no datastores it may see. A script that treats an empty result as “no backups exist” will report a healthy empty datastore and, if it drives alerting, will report nothing wrong at all.

That failure mode is worth designing against explicitly. Have the script assert that it can see at least one datastore and fail loudly if it cannot, rather than iterating over an empty list and exiting zero. A monitoring script that reports success when it can see nothing is worse than no monitoring, because it consumes the attention that would otherwise have noticed.

How to tell them apart in one step. Call GET /access/permissions with the token. It returns exactly what that auth-id is permitted on, from the server’s point of view. An empty or unexpectedly narrow result is a permissions problem; a populated one sends you back to the path.

The general habit. For any read-only automation against an API with per-object permissions, the first call should be one whose expected result you can assert on. “I got a 200” is not evidence that the query was the one you meant to ask.

Production considerations

Grant the narrowest role that works. DatastoreAudit is enough for reporting; DatastoreBackup and DatastoreAdmin are not needed to read status, and DatastoreAdmin can prune.
PBS is a separate trust boundary. A PVE token compromise should not imply a PBS one. Use different identities, and do not let PVE hold a PBS token that can delete backups — that is precisely the credential ransomware looks for.
Restrict port 8007. The PBS API listens there; limit it by firewall or network ACL to the hosts that need it.
Space out bulk calls. Add a short sleep between iterations when walking many groups; PBS is doing real work behind the status endpoints.
Never log the token. Mask it in any debug output, and keep it out of command lines.

Common mistakes

Using PVE’s = separator in the PBS Authorization header. PBS wants PBSAPIToken TOKENID:SECRET, and a malformed header returns the same 401 as a wrong secret.
Omitting the /admin prefix. /api2/json/datastore/... 404s in a way that looks like a missing datastore.
Looking for an endpoint that starts a backup. PBS is a destination; the request goes to PVE’s vzdump.
Treating an empty result as “no backups”. A token without ACLs sees an empty list, not a 403.
Pruning without dry-run first. There is no confirmation and no undo.
Reporting backup age without verification state. An unverified backup is a hypothesis; a failed one is worse than absent.
Running GC during the backup window. It is I/O heavy and its safety cutoff interacts with in-flight uploads.
Assuming a POST response is a result. GC, verify and prune all return a UPID and run asynchronously.

Key takeaways

PBS tokens are created with proxmox-backup-manager user generate-token and the secret is shown once.
The header is Authorization: PBSAPIToken TOKENID:SECRET — a colon, not PVE’s equals sign.
Datastore operations live under /api2/json/admin/datastore/{store}; /config/ is what is defined, /admin/ is what is happening.
PBS never initiates a backup. On-demand backups are requested from PVE via POST /nodes/{node}/vzdump.
GC, verify and prune return UPIDs and run asynchronously.
Always dry-run a prune and read every REMOVE line.
GET /status/datastore-usage returns estimated-full-date, computed by PBS from its own history.
Report on the verification state, not just on backup existence.
A token with no ACL returns an empty list rather than a 403, so assert on a non-empty expected result.

Authentication: the header is not the PVE one

The path prefix nearly every example gets wrong

PBS cannot be asked to take a backup

Maintenance operations, and following them

Reporting: PBS already computes the number you want

Production considerations

Common mistakes

Key takeaways

Knowledge check