{
  "openapi": "3.1.2",
  "info": {
    "title": "Papyr admin API",
    "description": "The admin API of a Papyr server, for its operator: the server's status and metrics, the stored rooms, removing one, and a backup of them. It is off until the server has a token (the setting Papyr:Admin:Token or Papyr:Admin:TokenFile, or the file admin-token in the data directory): off, every path under /api is 404 and this document does not exist. On, every request under /api carries the token as Authorization: Bearer <token>; without it, or with another one, the answer is 401 whatever the path and the method. With the token, a path of no route under /api is 404 and a route's path asked with another method 405. The paths are case-sensitive, every answer has Cache-Control: no-store, and none has a CORS header. Keep /api off the public site.",
    "version": "the server's version"
  },
  "paths": {
    "/api/status": {
      "get": {
        "tags": [
          "server"
        ],
        "summary": "The server's status",
        "description": "The server's version and start, its loaded and stored rooms, its relay connections, what the rooms' files hold and the data directory's volume has free (measured at most once every 5 seconds), what the stored blobs hold and how many there are, and its limits.",
        "operationId": "getStatus",
        "responses": {
          "200": {
            "description": "The status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminStatus"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "No token, or not the one set; no body.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer: the token is asked for as a bearer token.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "The room directory could not be measured. No body."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/api/rooms": {
      "get": {
        "tags": [
          "rooms"
        ],
        "summary": "A page of the stored rooms",
        "description": "The stored rooms sorted by id (by character code: -, digits, upper case, _, lower case), at most limit of them after the id after. Rooms created or removed while a client pages may or may not be named; none is named twice. Each id is the SHA-256 of a room's access key. An id opens nothing by itself. The id of an open room confirms a guess of its name, and whoever knows the name is a member: the listing, the events' tags and a backup show the text of every open room whose name can be guessed. Keep them as private as the data directory.",
        "operationId": "listRooms",
        "parameters": [
          {
            "name": "after",
            "in": "query",
            "description": "The room id the page starts after: the next of the page before. Left out: the first page.",
            "schema": {
              "maxLength": 43,
              "minLength": 43,
              "pattern": "^[A-Za-z0-9_-]{43}$",
              "type": "string"
            },
            "example": "Tq8Wn2Lr5Xy0Zb3Cd6Ef9Gh1Jk4Mn7Pq0Rs3Tu6Vw9X"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "The most rooms the page holds.",
            "schema": {
              "maximum": 1000,
              "minimum": 1,
              "type": "integer",
              "format": "int32",
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page; next is the after of the next page, null after the last one.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminRoomList"
                },
                "example": {
                  "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"
                }
              }
            }
          },
          "400": {
            "description": "An after that is no room id, a limit outside 1 to 1000, or either given twice.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "Ask with after set to a room id or left out, and limit to a whole number from 1 to 1000 or left out (100)."
              }
            }
          },
          "401": {
            "description": "No token, or not the one set; no body.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer: the token is asked for as a bearer token.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "The room directory could not be listed. No body."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/api/rooms/{id}": {
      "delete": {
        "tags": [
          "rooms"
        ],
        "summary": "Removes a room",
        "description": "Removes the room, loaded or not, and answers once it is gone: its connections are closed with 4008 (the pages say that the operator removed the room), then its files are removed. The server keeps no mark of it: a page that still holds the text stores the room again when it connects.",
        "operationId": "removeRoom",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The room's id: the SHA-256 of its access key. It opens nothing by itself.",
            "required": true,
            "schema": {
              "maxLength": 43,
              "minLength": 43,
              "pattern": "^[A-Za-z0-9_-]{43}$",
              "type": "string"
            },
            "example": "Tq8Wn2Lr5Xy0Zb3Cd6Ef9Gh1Jk4Mn7Pq0Rs3Tu6Vw9X"
          }
        ],
        "responses": {
          "204": {
            "description": "The room was removed."
          },
          "400": {
            "description": "An id that is no room id.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "Ask with a room id: 43 characters of A-Z a-z 0-9 - _."
              }
            }
          },
          "401": {
            "description": "No token, or not the one set; no body.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer: the token is asked for as a bearer token.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of the room is stored or loaded."
          },
          "500": {
            "description": "A file of the room could not be removed; what is left of the room loads again.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "The room's files could not be removed whole: the room is unloaded, and what is left of it loads. The server's log says why (event 28); remove it again once the cause is fixed."
              }
            }
          },
          "503": {
            "description": "The server is stopping."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/api/backup": {
      "get": {
        "tags": [
          "backup"
        ],
        "summary": "A backup of the stored rooms",
        "description": "A tar of every stored room's files, rooms/{id}.snapshot and rooms/{id}.log as they are named in the data directory, streamed as it is read (no length). Each room is taken whole at one moment while the server goes on. A backup cut off (the client went away, a room's files could not be read, the server stopped) ends without the tar's end: ask again. One backup runs at a time. An id opens nothing by itself. The id of an open room confirms a guess of its name, and whoever knows the name is a member: the listing, the events' tags and a backup show the text of every open room whose name can be guessed. Keep them as private as the data directory.",
        "operationId": "getBackup",
        "responses": {
          "200": {
            "description": "The tar (pax).",
            "headers": {
              "Content-Disposition": {
                "description": "attachment; filename=\"papyr-backup-<UTC date>.tar\"",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/x-tar": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "No token, or not the one set; no body.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer: the token is asked for as a bearer token.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "409": {
            "description": "A backup is running already.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "A backup is running already; ask again once it has ended."
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/api/openapi.json": {
      "get": {
        "tags": [
          "server"
        ],
        "summary": "This document",
        "description": "The OpenAPI document of the admin API, generated from its routes.",
        "operationId": "getOpenApiDocument",
        "responses": {
          "200": {
            "description": "The document (OpenAPI 3.1).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "No token, or not the one set; no body.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer: the token is asked for as a bearer token.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/api/metrics": {
      "get": {
        "tags": [
          "server"
        ],
        "summary": "The current values of the server's own metrics",
        "description": "Every instrument of the server's Papyr meter (docs/telemetry.md) and of the runtime's System.Runtime meter (dotnet.process.cpu.time, dotnet.process.memory.working_set, dotnet.gc.*, ...) with its kind, unit and description, and a series per set of attributes: a counter's sum since the start (since), an up-down counter's current sum, a gauge's last value, an observable instrument's value read now, a histogram's count, sum, minimum and maximum. At most 1000 series an instrument; beyond them, one series with the attribute otel.metric.overflow. As the Prometheus text (format=prometheus, or an Accept that prefers text/plain, as a scrape does): a family per instrument, its name with _ for each . (papyr_relay_updates_total), a counter with _total, an up-down counter or a gauge as a gauge, a histogram as a summary of _sum and _count; the attributes as labels, named the same way. No history (the counters start again with the server), and no metric of ASP.NET Core: those need an OpenTelemetry collector.",
        "operationId": "getMetrics",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "description": "json or prometheus (the text format 0.0.4). Left out: the Accept header decides, JSON unless it prefers text/plain to application/json, as a Prometheus scrape does.",
            "schema": {
              "pattern": "^(json|prometheus)$",
              "type": "string"
            },
            "example": "prometheus"
          }
        ],
        "responses": {
          "200": {
            "description": "The values, read now: JSON, or the Prometheus text format 0.0.4 (Content-Type text/plain; version=0.0.4; charset=utf-8) for format=prometheus or an Accept that prefers text/plain to application/json.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminMetrics"
                },
                "example": {
                  "at": "2026-11-15T15:04:05.123Z",
                  "since": "2026-11-15T14:51:28Z",
                  "instruments": [
                    {
                      "name": "papyr.relay.connection.closed",
                      "kind": "counter",
                      "unit": "{connection}",
                      "description": "Relay connections closed, by reason.",
                      "series": [
                        {
                          "attributes": {
                            "papyr.relay.close.reason": "client"
                          },
                          "value": 3
                        }
                      ]
                    },
                    {
                      "name": "papyr.room.removed",
                      "kind": "counter",
                      "unit": "{room}",
                      "description": "Rooms the operator removed through the admin API.",
                      "series": []
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "# HELP papyr_relay_connection_closed_total Relay connections closed, by reason. Unit: {connection}.\n# TYPE papyr_relay_connection_closed_total counter\npapyr_relay_connection_closed_total{papyr_relay_close_reason=\"client\"} 3\n# HELP papyr_room_removed_total Rooms the operator removed through the admin API. Unit: {room}.\n# TYPE papyr_room_removed_total counter\n"
              }
            }
          },
          "400": {
            "description": "A format other than json or prometheus, or two of them.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "Ask with format=json, format=prometheus, or without format: then the Prometheus text when the Accept header prefers text/plain to application/json, else JSON."
              }
            }
          },
          "401": {
            "description": "No token, or not the one set; no body.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer: the token is asked for as a bearer token.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "AdminInstrument": {
        "required": [
          "name",
          "kind",
          "unit",
          "description",
          "series"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The instrument's name, as docs/telemetry.md lists it."
          },
          "kind": {
            "type": "string",
            "description": "counter, upDownCounter, gauge or histogram; an observable instrument has the kind of its synchronous one."
          },
          "unit": {
            "type": "string",
            "description": "The unit the instrument declares (UCUM, such as By or {room}); empty when none."
          },
          "description": {
            "type": "string",
            "description": "The description the instrument declares; empty when none."
          },
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminSeries"
            },
            "description": "A series per distinct set of attributes, sorted by the attributes; empty before the first measurement."
          }
        },
        "description": "One instrument and its series."
      },
      "AdminLimits": {
        "required": [
          "updateBytes",
          "snapshotBytes",
          "storedUpdates",
          "storedBytes",
          "connectionsPerRoom",
          "loadedRooms",
          "queuedBytes",
          "serverConnections",
          "receiveBytes",
          "connectionsPerSource",
          "roomsPerSource",
          "newRoomsPerSourcePerHour",
          "storedRooms",
          "roomExpiryDays",
          "blobsEnabled",
          "blobMaxBytes",
          "roomBlobs",
          "roomBlobBytes",
          "totalBlobBytes",
          "uploadsPerSourcePerHour"
        ],
        "type": "object",
        "properties": {
          "updateBytes": {
            "type": "integer",
            "description": "The largest update, in bytes.",
            "format": "int32"
          },
          "snapshotBytes": {
            "type": "integer",
            "description": "The largest snapshot, in bytes.",
            "format": "int32"
          },
          "storedUpdates": {
            "type": "integer",
            "description": "The updates a room stores after its snapshot.",
            "format": "int32"
          },
          "storedBytes": {
            "type": "integer",
            "description": "What those updates may hold in a room's memory, in bytes.",
            "format": "int64"
          },
          "connectionsPerRoom": {
            "type": "integer",
            "description": "The connections of one room.",
            "format": "int32"
          },
          "loadedRooms": {
            "type": "integer",
            "description": "The rooms in memory.",
            "format": "int32"
          },
          "queuedBytes": {
            "type": "integer",
            "description": "What the messages a connection is behind on may hold, in bytes.",
            "format": "int64"
          },
          "serverConnections": {
            "type": "integer",
            "description": "The relay connections of the server.",
            "format": "int32"
          },
          "receiveBytes": {
            "type": "integer",
            "description": "What all incoming messages may hold together, in bytes.",
            "format": "int64"
          },
          "connectionsPerSource": {
            "type": "integer",
            "description": "The relay connections of one source.",
            "format": "int32"
          },
          "roomsPerSource": {
            "type": "integer",
            "description": "The rooms the connections of one source are in.",
            "format": "int32"
          },
          "newRoomsPerSourcePerHour": {
            "type": "integer",
            "description": "The rooms one source creates in an hour.",
            "format": "int32"
          },
          "storedRooms": {
            "type": "integer",
            "description": "The rooms the server stores; 0 is no limit.",
            "format": "int32"
          },
          "roomExpiryDays": {
            "type": "integer",
            "description": "The days without a write after which a stored room is removed; 0 keeps every room.",
            "format": "int32"
          },
          "blobsEnabled": {
            "type": "boolean",
            "description": "Whether the server takes blobs (Papyr:Blobs:Enabled); off, the blob routes answer 404."
          },
          "blobMaxBytes": {
            "type": "integer",
            "description": "The largest blob, in bytes (Papyr:Blobs:BlobBytes).",
            "format": "int64"
          },
          "roomBlobs": {
            "type": "integer",
            "description": "The blobs one room holds (Papyr:Blobs:RoomBlobs).",
            "format": "int32"
          },
          "roomBlobBytes": {
            "type": "integer",
            "description": "What one room's blobs may hold together, in bytes (Papyr:Blobs:RoomBytes).",
            "format": "int64"
          },
          "totalBlobBytes": {
            "type": "integer",
            "description": "What all blobs may hold together, in bytes (Papyr:Blobs:TotalBytes).",
            "format": "int64"
          },
          "uploadsPerSourcePerHour": {
            "type": "integer",
            "description": "The blobs one source uploads in an hour (Papyr:Blobs:UploadsPerSourcePerHour).",
            "format": "int32"
          }
        },
        "description": "The server's limits, each as its setting has it (Papyr:Relay:<Name>, Papyr:RoomExpiryDays, Papyr:Blobs:<Name>; docs/configuration.md)."
      },
      "AdminMetrics": {
        "required": [
          "at",
          "since",
          "instruments"
        ],
        "type": "object",
        "properties": {
          "at": {
            "type": "string",
            "description": "When the values were read (UTC, to the millisecond).",
            "format": "date-time"
          },
          "since": {
            "type": "string",
            "description": "Since when they are counted: the server's start (UTC, to the millisecond).",
            "format": "date-time"
          },
          "instruments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminInstrument"
            },
            "description": "Every instrument of the meters, by name."
          }
        },
        "description": "The current values of the instruments of the server's Papyr meter and the runtime's System.Runtime meter."
      },
      "AdminRoom": {
        "required": [
          "id",
          "bytes",
          "created",
          "lastWrite",
          "expires",
          "loaded",
          "connections"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The room's id: the SHA-256 of its access key, 43 characters of A-Z a-z 0-9 - _. It opens nothing by itself; the id of an open room confirms a guess of its name (whoever knows the name is a member)."
          },
          "bytes": {
            "type": "integer",
            "description": "What the room's files (its snapshot and its update log) hold, in bytes.",
            "format": "int64"
          },
          "created": {
            "type": "string",
            "description": "When the room was created (UTC): when it was loaded for the visit that wrote its first file; a room removed and written again is created anew. Its files' header holds it, and a snapshot, a backup and a restore keep it.",
            "format": "date-time"
          },
          "lastWrite": {
            "type": "string",
            "description": "The later of its files' last writes (UTC).",
            "format": "date-time"
          },
          "expires": {
            "type": [
              "null",
              "string"
            ],
            "description": "When the room expires (UTC): chosen when it was created, part of its link and its id, and never changed. The server removes it within the hour after, and refuses to join it from that moment. Null for a room without one.",
            "format": "date-time"
          },
          "loaded": {
            "type": "boolean",
            "description": "Whether the room is in memory."
          },
          "connections": {
            "type": "integer",
            "description": "The relay connections attached to the room; 0 when it is not loaded.",
            "format": "int32"
          }
        },
        "description": "A stored room."
      },
      "AdminRoomList": {
        "required": [
          "rooms",
          "next"
        ],
        "type": "object",
        "properties": {
          "rooms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminRoom"
            },
            "description": "The rooms of the page, at most limit of them."
          },
          "next": {
            "type": [
              "null",
              "string"
            ],
            "description": "The after of the next page; null after the last page."
          }
        },
        "description": "A page of the stored rooms, sorted by id (by character code)."
      },
      "AdminSeries": {
        "required": [
          "attributes"
        ],
        "type": "object",
        "properties": {
          "attributes": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "The attributes, each value as a string; empty for the measurements without attributes."
          },
          "value": {
            "type": "number",
            "description": "A counter's sum since the start, an up-down counter's current sum, a gauge's last value, an observable instrument's value read now (an integer for an instrument of integers). Not for a histogram."
          },
          "count": {
            "type": "integer",
            "description": "A histogram's count of measurements. Only for a histogram.",
            "format": "int64"
          },
          "sum": {
            "type": "number",
            "description": "A histogram's sum of measurements. Only for a histogram."
          },
          "min": {
            "type": "number",
            "description": "A histogram's smallest measurement. Only for a histogram."
          },
          "max": {
            "type": "number",
            "description": "A histogram's largest measurement. Only for a histogram."
          }
        },
        "description": "The values of one set of attributes of an instrument: value, or for a histogram count, sum, min and max."
      },
      "AdminStatus": {
        "required": [
          "version",
          "startedAt",
          "loadedRooms",
          "storedRooms",
          "connections",
          "roomBytes",
          "freeBytes",
          "blobBytes",
          "blobCount",
          "limits"
        ],
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "description": "The server's version, from its build: the version and, for a build from a git checkout, '+' and the commit."
          },
          "startedAt": {
            "type": "string",
            "description": "When the server started (UTC).",
            "format": "date-time"
          },
          "loadedRooms": {
            "type": "integer",
            "description": "The rooms in memory.",
            "format": "int32"
          },
          "storedRooms": {
            "type": "integer",
            "description": "The rooms with a file in the data directory.",
            "format": "int32"
          },
          "connections": {
            "type": "integer",
            "description": "The relay connections attached to the loaded rooms.",
            "format": "int32"
          },
          "roomBytes": {
            "type": "integer",
            "description": "What the stored rooms' files hold together, in bytes; measured at most once every 5 seconds.",
            "format": "int64"
          },
          "freeBytes": {
            "type": "integer",
            "description": "What the data directory's volume has free, in bytes; measured with roomBytes.",
            "format": "int64"
          },
          "blobBytes": {
            "type": "integer",
            "description": "What the stored blobs hold together, in bytes; kept as blobs are stored and removed, not measured.",
            "format": "int64"
          },
          "blobCount": {
            "type": "integer",
            "description": "The blobs the server stores; kept as blobBytes is.",
            "format": "int32"
          },
          "limits": {
            "description": "The server's limits.",
            "$ref": "#/components/schemas/AdminLimits"
          }
        },
        "description": "The server's state: its version, when it started, its rooms and connections, the space of its data directory, its blobs, and its limits."
      }
    },
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "description": "The server's admin token (at least 32 characters), as Authorization: Bearer <token>.",
        "scheme": "bearer"
      }
    }
  },
  "tags": [
    {
      "name": "server",
      "description": "The server's status, its metrics, and this document."
    },
    {
      "name": "rooms",
      "description": "The stored rooms: listing them, removing one."
    },
    {
      "name": "backup",
      "description": "A backup of the stored rooms."
    }
  ]
}
