The Uplivra API

Get a token

On the Uplivra server, run:

sudo uplivra token create -name "backup script"

The token is shown once, so copy it somewhere safe. Add -read-only for a token that can read everything but change nothing. sudo uplivra token list shows your tokens (never their values), and sudo uplivra token revoke -id 3 stops one working at once.

Send the token with every request:

curl -H "Authorization: Bearer uv_admin_…" https://uplivra.example.com/api/v1/devices

The description

The full description is at https://<your server>/api/v1/openapi.json (OpenAPI 3.1, no token needed). Load it into Postman, Insomnia or a code generator.

Paging

Lists return a JSON array of up to 100 items. Add limit (at most 1000) for bigger pages. When there's more, the response has two headers:

X-Next-Cursor: 1234
Link: </api/v1/devices?cursor=1234&limit=100>; rel="next"

Ask again with cursor set to that value and the same filters. When X-Next-Cursor is missing, you have everything.

Rate limits

Each token can make 300 requests a minute, in bursts of up to 60. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit, the answer is 429 Too Many Requests with Retry-After in seconds. An address that sends more than 20 wrong tokens a minute is slowed down the same way.

The audit log

GET /api/v1/audit returns the audit log, newest first, with the same filters as the web page: since, until, actor, action, result and correlation_id. Read-only tokens can use it, which suits a SIEM or a compliance script. Each entry carries its hash, so you can check the chain yourself. Every read is itself recorded, and everything a token changes is recorded as token:<name>.