The admin API
An HTTP API for the operator under /api: status, metrics, the stored rooms, removing a room, a backup, and an
OpenAPI document. It is off until it has a token; then every request must carry it.
| Route | What it does |
|---|---|
GET /api/status |
Version, start time, counts, free disk, the blobs, the limits. |
GET /api/rooms?limit=&after= |
The stored rooms, paged. |
DELETE /api/rooms/{id} |
Remove a room, loaded or not. |
GET /api/metrics |
The server’s metrics as JSON or Prometheus text. |
GET /api/backup |
A tar of every stored room and its blobs. |
GET /api/openapi.json |
The API’s description, OpenAPI 3.1. |
Turning it on
The API is on when the server finds a token at its start, in one of three ways:
-
The token file in the data directory, made by the verb
token, then a restart:Papyr.Server token # from the source: dotnet run --project src/Papyr.Server -- token docker run --rm -v papyr-data:/data papyr token # the image: the same volume as the serverIt writes a new random token (32 random bytes, base64url, 43 characters) to
admin-tokenin the data directory (/data/admin-tokenin the image), mode 0600, prints the token once on stdout and the path on stderr. It reads the same settings as the server, never overwrites a file (then it writes nothing and exits 1), and refuses to run whilePapyr:Admin:Tokenis set. Restart the server after it. - A file of your own:
Papyr__Admin__TokenFile=/run/secrets/papyr-admin-token(a Docker or Compose secret), or put it at the default path. At least 32 characters, no blank or control character (a trailing line end is fine), mode 0600:openssl rand -base64 32 > admin-token && chmod 600 admin-token. - The setting
Papyr__Admin__Token=<the token>.
What happens when the token is missing or set twice: configuration.md, “The admin API”. The start logs event 23
with the setting the token came from, never the token.
Reading the token of the file: docker run --rm -v papyr-data:/data busybox cat /data/admin-token.
Rotating it: delete the file, run the verb again and restart; with the setting, change it and restart. The old
token stops working at the restart.
Asking it
Send the token as Authorization: Bearer <token>; the query string and cookies are ignored.
TOKEN=$(cat /path/to/admin-token)
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/api/status
| Answer | When |
|---|---|
401, WWW-Authenticate: Bearer, no body |
Missing or wrong token, whatever the path under /api and the method. Only the token’s holder learns which routes exist. |
404 |
A path of no route; also /API/... or /Api/... (paths are lower case and case-sensitive), with or without the token. |
405 with Allow |
Another method on a route. |
400 |
A bad query or id. |
Wrong tokens are counted (papyr.admin.unauthorized) and logged (event 24), never throttled, so nobody can lock the
operator out by guessing. Every answer has Cache-Control: no-store and no CORS header. While the API is on, a folder
api in the web root is never served.
Status
{"version":"1.0.0+0bc9bb09c9370cc76095f208017caae541cf5c18","startedAt":"2026-11-15T13:27:53.4563904Z","loadedRooms":0,"storedRooms":2,"connections":0,"roomBytes":122,"freeBytes":2861641728,"blobBytes":0,"blobCount":0,"limits":{"updateBytes":1048576,"snapshotBytes":8388608,"storedUpdates":2000,"storedBytes":4194304,"connectionsPerRoom":32,"loadedRooms":1000,"queuedBytes":16777216,"serverConnections":256,"receiveBytes":268435456,"connectionsPerSource":32,"roomsPerSource":16,"newRoomsPerSourcePerHour":10,"storedRooms":0,"roomExpiryDays":0,"blobsEnabled":false,"blobMaxBytes":5242880,"roomBlobs":256,"roomBlobBytes":52428800,"totalBlobBytes":1073741824,"uploadsPerSourcePerHour":60}}
| Field | Meaning |
|---|---|
version |
The build’s version; the commit after the +. |
startedAt |
When the server started (UTC). |
loadedRooms, connections |
Rooms in memory and the relay connections in them. |
storedRooms |
Rooms with a file (as event 20 and papyr.room.stored.count count them). |
roomBytes, freeBytes |
What the room files hold together, and what the volume has free. Measured at most once every 5 seconds. |
blobBytes, blobCount |
What the stored blobs hold together, in bytes, and how many there are. Kept as blobs are stored and removed, so current. Uploads in progress are not counted. These count with the blobs off too, for blobs stored before. |
limits |
The settings as they are (configuration.md); storedRooms and roomExpiryDays of 0 mean none. The blob limits: blobsEnabled (Papyr:Blobs:Enabled), blobMaxBytes (BlobBytes, the largest blob), roomBlobs and roomBlobBytes (RoomBlobs, RoomBytes, one room’s), totalBlobBytes (TotalBytes) and uploadsPerSourcePerHour. blobMaxBytes is not blobBytes: the latter is what the server holds. |
Rooms
curl -s -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:8080/api/rooms?limit=1"
{"rooms":[{"id":"Tq8Wn2Lr5Xy0Zb3Cd6Ef9Gh1Jk4Mn7Pq0Rs3Tu6Vw9X","bytes":61,"created":"2026-11-02T08:14:03.117Z","lastWrite":"2026-11-15T13:27:58.4922361Z","expires":"2026-12-02T08:14:00Z","loaded":false,"connections":0}],"next":"Tq8Wn2Lr5Xy0Zb3Cd6Ef9Gh1Jk4Mn7Pq0Rs3Tu6Vw9X"}
Rooms come sorted by id, at most limit a page (1 to 1000; 100 when left out). next is the after of the next page
(?limit=1&after=Tq8Wn...), null after the last. Each room has its id, the bytes of its files, when it was created
(kept across snapshots, backups and restores; a room removed and written again is created anew), its last write,
when it expires (expires, null for a room without an expiry: one chosen when the room was made, part of its link,
after which the server removes it within the hour), whether it is loaded and its connections. Rooms created or removed while you page may or may not show up; none is
named twice.
A room id opens nothing by itself, but the id of an open room confirms a guess of its name: keep the listing as private
as the data directory (operations.md, “What the server sees”).
Removing a room
curl -s -i -X DELETE -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/api/rooms/tihLUkOyO-_YJDLS1gZrFYzozrYr_fXeqB7AtN0U18c
Every connection of the room is closed with 4008 (the pages stop syncing and say the operator removed the room; the text stays on the page to copy), then its files are removed and its place among the stored rooms is free.
| Answer | When |
|---|---|
204 |
Removed. Logged as event 25 with the room’s tag, counted in papyr.room.removed. |
404 |
Nothing of the room is stored or loaded. |
400 |
Not a room id. |
500 |
A file could not be removed (event 28 says why). What is left loads again: fix the cause and remove it again. |
503 |
The server is stopping. |
The server keeps no mark of a removed room: a page that was offline during the removal and still holds the text stores the room again when it connects. An open room’s name stays free to use.
Metrics
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/api/metrics
{"at":"2026-11-15T15:55:31.141Z","since":"2026-11-15T15:51:36.419Z","instruments":[
{"name":"papyr.admin.unauthorized","kind":"counter","unit":"{request}","description":"Requests to the admin API answered 401, by reason.","series":[{"attributes":{"papyr.admin.unauthorized.reason":"missing"},"value":2},{"attributes":{"papyr.admin.unauthorized.reason":"wrong"},"value":1}]},
{"name":"papyr.relay.connection.count","kind":"upDownCounter","unit":"{connection}","description":"Open relay connections.","series":[{"attributes":{},"value":0}]},
{"name":"papyr.room.stored.count","kind":"upDownCounter","unit":"{room}","description":"Rooms with a file: an update log or a snapshot.","series":[{"attributes":{},"value":2}]},
...]}
The current values of the Papyr meter (telemetry.md, “Metrics”) and of the runtime’s System.Runtime meter
(dotnet.process.cpu.time, dotnet.process.memory.working_set, dotnet.gc.*, …). at is when they were read,
since the server’s start. Each instrument has its name, kind (counter, upDownCounter, gauge,
histogram), unit, description and a series per set of attributes. A series has a value: a counter’s sum since
since, an up-down counter’s current sum, a gauge’s last value; a histogram’s series has count, sum, min and
max instead. An instrument that recorded nothing has "series":[]. An up-down counter read while it changes can be
off for a moment, even below 0; the next read is right. The shape is pinned by spec/admin-metrics.sample.json and
described in the OpenAPI document (getMetrics).
The same values as Prometheus text format 0.0.4:
curl -s -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:8080/api/metrics?format=prometheus"
# HELP papyr_relay_connection_closed_total Relay connections closed, by reason. Unit: {connection}.
# TYPE papyr_relay_connection_closed_total counter
papyr_relay_connection_closed_total{papyr_relay_close_reason="client"} 9
?format=prometheus or ?format=json chooses; without format, an Accept that prefers text/plain over
application/json (a Prometheus scrape) gets the text, anything else JSON. Names have _ for every other character
(papyr.relay.updates is papyr_relay_updates_total): a counter is a counter with _total, an up-down counter or
gauge a gauge, a histogram a summary with _sum and _count. Attributes are labels, named the same way. The
scrape configuration, a Grafana dashboard and alert rules are in deploy/grafana/.
What it is not: no history (for a rate, read twice or let Prometheus scrape), no metrics of ASP.NET Core or Kestrel
(telemetry.md, “Reading the metrics without a collector”), nothing that survives a restart. The server counts only
while the API is on. A read costs about 0.1 ms of CPU and holds no room id, token or address.
Backup
curl -sS -f -H "Authorization: Bearer $TOKEN" -o backup.tar http://127.0.0.1:8080/api/backup
Streams a tar (application/x-tar, Content-Disposition: attachment; filename="papyr-backup-<UTC date>.tar") of
every stored room’s files and its blobs, each room taken whole at one moment while the server goes on. One backup runs
at a time, a scheduled one included; a second gets 409. A backup that is cut off ends without the tar’s end, so
curl -f fails and the restore refuses it; ask again. Event 31 logs how each backup ended. What the tar holds, how a
cut-off backup shows and how to restore: operations.md, “Backup and restore”. Keep the tar as private as the data
directory.
The OpenAPI document
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/api/openapi.json > papyr-admin.json
An OpenAPI 3.1 document: every route with its parameters and bounds, every
status, the schemas of the answers, examples, and the bearer scheme. Made from the routes at each request, so it
describes the server that answers; info.version is the server’s version. Each operation has a fixed operationId
(getStatus, listRooms, removeRoom, getBackup, getMetrics, getOpenApiDocument) and a tag (server,
rooms, backup). A copy is in the repository, openapi.json; a test keeps it equal.
The admin page
/admin is a page for the same API. It asks for the token (kept in the tab’s sessionStorage until “Sign out”, a 401
or the tab’s end; sent only as the Authorization header) and has four tabs, the selected one in the address
(/admin#rooms):
- Overview: the status, the limits and the backup download.
- Metrics: every instrument as a table, with the change since the page was opened, the rate over the last interval and a trend line. Reads every 5 seconds while shown (Pause stops it).
- API: the OpenAPI document rendered, a “Copy as curl” line per operation, and the raw JSON.
- Rooms: the list with “Load more” and “Load all rooms” (at most 5000), a room found by its name (the page derives
the id; needs HTTPS or
localhost), delete one or many (checkboxes, Shift+click for a range; three at a time, with Cancel), and the backup download. Only a room found by name has an “Open” link: no room opens by its id.
The page is static and public; without a token it says that the API is off and how to turn it on. The backup goes
through the browser’s memory, so for a large store use curl (the page shows the command). Keep /admin off the
public site together with /api.
Keep /api inside
The API answers on the server’s own port, the one the proxy forwards to the world, and the token is its only lock. Keep it off the public site:
- the proxy answers
/apiand/admin, and everything under them, with 404 (the examples inself-hosting.mddo); - ask the server’s port directly from inside (
curl http://127.0.0.1:8080/api/status), or through an SSH tunnel.
Without such a rule the API still needs the token, but a token that leaks (a shell history, a screenshot) opens it to anyone.
With TLS on (Papyr:Tls:*) the HTTPS listener serves /api too, on every address by default, and no proxy
stands in front of it. Keeping the HTTP listener on 127.0.0.1 does not keep the API inside then: bind the HTTPS
listener too (Papyr:Tls:Address), or accept that the token is the lock (configuration.md, “TLS”).