1Server admin REST API 2--------------------- 3 4The standalone server provides a RESTful JSON API for administration. 5The API is activated with the `--web-admin-port` command line parameter. 6For security, it is important that the API is not publicly accessible! 7If public access is needed (e.g. to list available sessions,) create a 8web application that communicates with the server and presents the data. 9 10The body of POST and PUT messages should be a JSON document with the content type `application/json`. 11 12## Server status 13 14`GET /api/status/` 15 16Returns server status information: 17 18 { 19 "started": "yyyy-mm-dd hh:mm:ss" (server startup timestamp UTC+0) 20 "sessions": integer (number of active sessions) 21 "maxSessions": integer (max active sessions) 22 "users": integer (number of active users) 23 "ext_host": "hostname" (server's hostname, as used in session listings) 24 "ext_port": integer (server's port, as used in session listings) 25 } 26 27 28## Serverwide settings 29 30`GET /api/server/` 31 32Returns a list of server settings: 33 34 { 35 "clientTimeout": seconds (connection timeout) 36 "sessionSizeLimit": bytes (maximum session size, or 0 for unlimited) 37 "sessionCountLimit": integer (maximum number of active sessions) 38 "persistence": boolean (allow sessions to persist without users) 39 "allowGuestHosts": boolean (allow users without the HOST privilege to host sessions) 40 "idleTimeLimit": seconds (delete session after it has idled for this long) 41 (0 means no time limit) 42 "serverTitle": "string" (title to be shown in the login box) 43 "welcomeMessage": "string") (welcome chat message sent to new users) 44 "privateUserList": boolean (if true, user list is never included in announcements) 45 "allowGuests": boolean (allow unauthenticated logins) 46 "archive": boolean (archive file backed sessions instead of deleting them) 47 "extauth": boolean (enable external authentication) 48 (auth server URL must have been set via command line parameter) 49 "extauthkey": "key string" (ext-auth server public key) 50 "extauthgroup": "group id" (user group id. Leave blank to use default group) 51 "extauthfallback": boolean (fall back to guest logins if ext-auth server is not reachable) 52 "extauthmod": boolean (respect ext-auth user's MOD flag) 53 "reporttoken": "token" (authorization token for abuse report server) 54 "logpurgedays": integer (log entries older than this many days are automatically purged) 55 (0 means logs are not purged) 56 "autoResetThreshold": bytes (session size at which autoreset request is sent) 57 (Should be less than sessionSizeLimit. Can be overridden per-session) 58 "customAvatars": boolean (allow use of custom avatars. Custom avatars override ext-auth avatars) 59 "extAuthAvatars": boolean (allow use of ext-auth avatars) 60 } 61 62To change any of these settings, send a `PUT` request. Settings not 63included in the request are not changed. 64 65Values that accept seconds also accept time strings like "1.5 d" 66Values that accept bytes also accept file sizes like "15 mb" 67 68Implementation: `serverJsonApi @ src/server/multiserver.cpp` 69 70See also `src/srver/serverconfig.h` for the most up to date list of supported settings. 71 72 73## Sessions 74 75Get a list of active sessions: `GET /api/sessions/` 76 77Returns: 78 79 [ 80 { 81 "id": "uuid" (unique session ID) 82 "alias": "alias" (ID alias, if set) 83 "protocol": "xx:1.2.3" (protocol version) 84 "userCount": integer (number of users) 85 "maxUserCount": integer (maximum number of users) 86 "founder": "username" (name of the user who created the session) 87 "title": "string" (session title) 88 "persistent": boolean (is persistence activated. Only included if feature is enabled serverwide) 89 "hasPassword": boolean (is the session password protected) 90 "closed": boolean (is the session closed to new users) 91 "authOnly": boolean (are only registered users allowed) 92 "nsfm": boolean (does this session contain age restricted content) 93 "startTime": "timestamp" () 94 "size": bytes (session history size) 95 }, ... 96 ] 97 98Implementation: `callSessionJsonApi @ src/libserver/sessionserver.cpp` 99 100Get detailed information about a session: `GET /api/sessions/:id/` 101 102 { 103 *same fields as above 104 "maxSize": bytes (maximum allowed size of the session) 105 "resetThreshold": bytes (autoreset threshold) 106 "deputies": boolean (are trusted users allowed to kick non-trusted users) 107 "hasOpword": boolean (is an operator password set) 108 "users": [ 109 { 110 "id": integer (user ID. Unique only within the session) 111 "name": "user name" 112 "ip": "IP address" 113 "auth": boolean (is authenticated), 114 "op": boolean (is a session owner), 115 "muted": boolean (is blocked from chat), 116 "mod": boolean (is a moderator), 117 "tls": boolean (is using a secure connection), 118 "online": boolean (if false, this user is no longer logged in) 119 }, ... 120 ], 121 "listings": [ 122 { 123 "id": integer (listing entry ID number) 124 "url": "url" (list server address) 125 "roomcode": "room code" (the room code, if provided) 126 "private": boolean (is this a private listing) 127 }, ... 128 ] 129 } 130 131Updating session properties: `PUT /api/sessions/:id/` 132 133The following properties can be changed: 134 135 { 136 "closed": true/false, 137 "authOnly": true/false, 138 "persistent": true/false (only when persistence is enabled serverwide), 139 "title": "new title", 140 "maxUserCount": user count (does not affect existing users), 141 "resetThreshold": size in bytes, or 0 to disable autoreset, 142 "password": "new password", 143 "opword": "new operator password", 144 "preserveChat": true/false (include chat in history), 145 "nsfm": true/false, 146 "deputies": true/false 147 } 148 149To send a message to all session participants: `PUT /api/sessions/:id/` 150 151 { 152 "message": "send a message to all participants", 153 "alert": "send an alert to all participants" 154 } 155 156To shut down a session: `DELETE /api/sessions/:id/` 157 158Implementation: `callJsonApi @ src/shared/server/session.cpp` 159 160### Session users 161 162Kick a user from a session: `DELETE /api/sessions/:sessionid/:userId/` 163 164Change user properties: `PUT /api/sessions/:sessionid/:userId/` 165 166 { 167 "op": true/false (op/deop the user) 168 } 169 170To send a message to an individual user: `PUT /api/sessions/:sessionid/:userId/` 171 172 { 173 "message": "message text" 174 } 175 176Implementation: `callUserJsonApi @ src/shared/server/session.cpp` 177 178## Logged in users 179 180`GET /api/users/` 181 182Returns a list of logged in users: 183 184 [ 185 { 186 "session": "session ID" (if empty, this user hasn't joined any session yet) 187 "id": integer (unique only within the session), 188 "name": "user name", 189 "ip": "IP address", 190 "auth": boolean (is authenticated), 191 "op": boolean (is session owner), 192 "muted": boolean (is blocked from chat), 193 "mod": boolean (is a moderator), 194 "tls": boolean (is using a secure connection) 195 } 196 ] 197 198Implementation: `callUserJsonApi @ src/shared/server/sessionserver.cpp` 199 200## User accounts 201 202`GET /api/accounts/` 203 204Returns a list of registered user accounts: 205 206 [ 207 { 208 "id": integer (internal account ID number) 209 "username": "username" 210 "locked": boolean (is this account locked) 211 "flags": "flag1,flag2" (comma separated list of flags) 212 }, ... 213 ] 214 215Possible user flags are: 216 217 * HOST - this user can host new sessions (useful when allowGuestHosts is set to false) 218 * MOD - this user is a moderator (has permanent OP status, may enter locked sessions) 219 220To add a new user: `POST /api/accounts/` 221 222 { 223 "username": "username to register", 224 "password": "user's password", 225 "locked": true/false, 226 "flags": "" 227 } 228 229To edit an user: `PUT /api/accounts/:id/` 230 231 { 232 "username": "change username", 233 "password": "change password", 234 "locked": change lock status, 235 "flags": "change flags" 236 } 237 238To delete a user: `DELETE /api/accounts/:id/` 239 240Implementation: `accountsJsonApi @ src/server/multiserver.cpp` 241 242## Banlist 243 244`GET /api/banlist/` 245 246Returns a list of serverwide IP bans: 247 248 [ 249 { 250 "id": ban entry ID number, 251 "ip": "banned IP address", 252 "subnet": "subnet mask (0 means no mask, just the individual address is banned)", 253 "expires": "ban expiration date", 254 "comment": "Freeform comment about the ban", 255 "added": "date when the ban was added" 256 } 257 ] 258 259To add a ban, make a `POST` request to `/api/banlist/`: 260 261 { 262 "ip": "IP to ban", 263 "subnet: "Subnet mask (0 to ban just the single address)", 264 "expires": "expiration date", 265 "comment": "freeform comment" 266 } 267 268To delete a ban, make a `DELETE /api/banlist/:id/` request. 269 270Implementation: `banlistJsonApi @ src/server/multiserver.cpp` 271 272## List server whitelist 273 274`GET /api/listserverwhitelist/` 275 276Returns: 277 278 { 279 "enabled": boolean 280 "whitelist": [ 281 "regexp", 282 ... 283 ] 284 } 285 286If `enabled` is false, the whitelist is not applied and any list server 287can be used. To block all list servers, set `enabled` to true and leave the 288whitelist array empty. 289 290The `whitelist` array is a list of regular expressions that match list server 291URLs. (For example: `^https?://drawpile.net/api/listserver`) 292 293To change the whitelist, make a PUT request with a body in the same format 294as returned by the GET request. 295 296Implementation: `listserverWhitelistJsonApi @ src/server/multiserver.cpp` 297 298 299## Server log 300 301`GET /api/log/` 302 303The following query parameters can be used to filter the result set: 304 305 * ?page=0/1/2/...: show this page 306 * ?session=id: show messages related to this session 307 * ?after=timestamp: show messages after this timestamp 308 309Returns: 310 311 [ 312 { 313 "timestamp": "log entry timestamp (UTC+0)", 314 "level": "log level: Error/Warn/Info/Debug", 315 "topic": "what this entry is about", 316 "session": "session ID (if related to a session)", 317 "user": "ID;IP;Username triple (if related to a user)", 318 "message": "log message" 319 }, ... 320 ] 321 322Possible topics are: 323 324 * Join: user join event 325 * Leave: user leave event 326 * Kick: this user was kicked from the session 327 * Ban: this user was banned from the session 328 * Unban: this user's ban was lifted 329 * Op: this user was granted session ownership 330 * Deop: this user's session owner status was removed 331 * Mute: this user was blocked from chat 332 * Unmute: this user can chat again 333 * BadData: this user sent an invalid message 334 * RuleBreak: this committed a protocol violation 335 * PubList: session announcement related messages 336 * Status: general status messages 337 338Implementation: `logJsonApi @ src/server/multiserver.cpp` 339