REST API

The NGBackup Web Console exposes a versioned REST API under /api/v1/. Everything the console UI does — running jobs, browsing restore points, reading health — is available to machine clients through the same endpoints.

The OpenAPI document

The API describes itself. Fetch the generated OpenAPI 3.1 document from a running Web Console (authenticated, like every endpoint):

curl -H "Authorization: Bearer $NGB_TOKEN" \
  https://console.example.com/api/v1/openapi.json

The document is generated from the server’s own handler annotations at build time, so it cannot drift from the routes it describes. Current coverage: tokens, auth, operations, restore, directors, storage-media, stats. Groups still marked internal (config pipeline, admin, plugins, reports, automation, advanced) are added as they stabilize — treat any endpoint absent from the document as subject to change without notice.

Authentication: personal API tokens

Interactive users log in with a session cookie; machine clients use personal API tokens — bearer credentials with the issuing user’s role snapshotted at creation time.

Mint one in the UI (Security → API Tokens) or over the API using a browser session:

# Returns the token summary plus "plaintext" — shown exactly ONCE.
curl -X POST https://console.example.com/api/v1/tokens \
  -H "Cookie: backupweb_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name": "terraform-prod"}'

Store the plaintext value (ngbt_…) — the server keeps only its SHA-256. Then authenticate any request with it:

curl -H "Authorization: Bearer ngbt_…" \
  https://console.example.com/api/v1/operations/jobs

Tokens act with the role they were minted under (admin, operator, readonly, or a custom capability role). Revoke at any time — revocation is immediate and the row is kept as an audit trail:

curl -X DELETE -H "Authorization: Bearer ngbt_…" \
  https://console.example.com/api/v1/tokens/<id>

Minting and revoking are audit-logged (api_token.create / api_token.revoke).

Quick tour

AUTH='Authorization: Bearer ngbt_…'
BASE=https://console.example.com/api/v1

# Director health roll-up
curl -H "$AUTH" $BASE/director/health

# Recent jobs
curl -H "$AUTH" $BASE/operations/jobs/recent

# Run a job
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"job": "BackupWebServer", "level": "Incremental"}' \
  $BASE/operations/jobs/run

# Search the catalog for a file across a restore chain
curl -H "$AUTH" "$BASE/restore/bvfs/search?jobids=101,102&q=config.ini"

Request and response schemas for every covered endpoint, including status codes and parameter types, live in the OpenAPI document above — point any OpenAPI-aware client (Swagger UI, Postman, openapi-generator) at it.

Alert events for integrations

Notification channels (email/webhook, Administration → Notifications) subscribe to event patterns. Machine-relevant actions include:

Action	Fires when
job.completed.error / job.completed.warning	a job finishes badly
client.silence.warn / client.silence.crit	a client has had no successful backup for longer than the warn/crit threshold
client.silence.ok	a previously-silent client recovers
api_token.create / api_token.revoke	token lifecycle (audit)

Thresholds are operator-configurable (Administration → Monitoring); webhook channels can target PagerDuty/OpsGenie-style ingestion URLs.