Papyr Write together in Markdown. The server can't read it. Try it GitHub

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 server
    

    It writes a new random token (32 random bytes, base64url, 43 characters) to admin-token in the data directory (/data/admin-token in 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 while Papyr:Admin:Token is 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 /api and /admin, and everything under them, with 404 (the examples in self-hosting.md do);
  • 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”).