Administration

The /api/admin/* endpoints are restricted to platform administrators. The caller must (a) have an Administrator record AND (b) be the owner of the system organization named The Public. Anything else returns 403 Forbidden. These endpoints are not part of the public API contract and may change without notice.

A related diagnostic surface (the architecture-aggregates endpoints) has the same Public-owner gate but is documented under Utility Endpoints.

Endpoint table

Listing users

GET /api/admin/users?page=1&limit=25&search=octo

{
  "users": [
    {
      "id": "u1",
      "email": "octo@example.com",
      "username": "octo",
      "displayName": "Octo",
      "avatar": null,
      "bio": null,
      "emailVerified": true,
      "cleared": false,
      "accountStatus": "active",
      "customerStatus": "free",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "isAdministrator": false
    }
  ],
  "pagination": { "total": 1024, "limit": 25, "offset": 0, "page": 1, "hasMore": true }
}

Creating a user

POST /api/admin/users
Content-Type: application/json

{
  "email": "user@example.com",
  "username": "user1",
  "password": "min8chars",
  "displayName": "User One",
  "emailVerified": false,
  "isAdministrator": false,
  "customerStatus": "free"
}

Hashes the password, optionally marks emailVerified, optionally promotes to administrator, and adds the user to The Public. If the user is not pre-verified, a verification email is sent.

Updating a user

PUT /api/admin/users/u1
Content-Type: application/json

{ "emailVerified": true, "customerStatus": "subscriber:monthly", "accountStatus": "active", "isAdministrator": true }

Any subset of email, username, displayName, avatar, bio, emailVerified, cleared, accountStatus, customerStatus, isAdministrator may be supplied. Email/username uniqueness is re-checked. Promoting/demoting administrator updates the Administrator table.

accountStatus (see Account status) must be one of probation, active, restricted, suspended, banned. Setting it to active also sets cleared: true (unless cleared is sent explicitly in the same request). Setting it to banned deletes the target's sessions and sync tokens in the same transaction, forcing a full logout. Guards: an admin cannot change their own accountStatus, and cannot restrict/suspend/ban the last remaining administrator.

Setting a user's password

POST /api/admin/users/u1/password
Content-Type: application/json

{ "password": "min8chars" }

Sets the password and invalidates all of the target user's sessions in the same transaction.

Account status

Every user carries an accountStatus lifecycle value that can limit or block their write actions. The five values are probation (new signup, plain posts only, rate-limited), active (full access), restricted and suspended (read-only, can appeal), and banned (terminal, logged out). New signups start at probation; on email verification the account auto-transitions to active or restricted based on its spam score. Enforcement of these limits is server-side and gated by a deployment flag; when enforcement is on, blocked writes return the account-status error codes.

Setting account status in bulk

PATCH /api/admin/users/bulk-account-status
Content-Type: application/json

{ "userIds": ["u1", "u2"], "accountStatus": "restricted" }

Sets accountStatus for every listed user. Side effects mirror the single-user PUT:

• active also sets cleared: true (not-spam semantics).
• banned deletes those users' sessions and sync tokens (force logout everywhere).

Returns { "updated": N }.

Purging a user's content

POST /api/admin/users/u1/purge
Content-Type: application/json

{
  "categories": { "messages": true, "directMessages": true, "documents": true, "lists": true },
  "reason": "Confirmed spam account",
  "dryRun": false
}

Deletes the target user's authored content while leaving the User row and its accountStatus intact, so a restricted / suspended / banned account keeps its lock after its content is removed. Each purge writes one row to the UserContentPurge audit table.

Body fields (all optional)

• messages: every Message the user authored (posts + replies), their digs/reports, external cross-posts, and message/video/DM-image blobs.
• directMessages: DirectMessage rows they sent (outbound only), plus DM-image blobs. Received DMs are left alone.
• documents: their Documents and Folders (with collaborators, share links, invites, presence) plus document blobs.
• lists: their Lists and ListFolders (with properties, rows, watchers, share links, invites).

Dry-run response 200 OK

{ "dryRun": true, "counts": { "messages": 42, "directMessages": 3, "documents": 1, "folders": 0, "lists": 2, "listFolders": 0 } }

Purge response 200 OK

{ "dryRun": false, "counts": { "messages": 42, "directMessages": 3, "documents": 1, "folders": 0, "lists": 2, "listFolders": 0 } }

The purge is irreversible. It runs in batches so a prolific account's content does not blow a single transaction, and it never touches analytics (the user still exists).

PATCH /api/admin/users/bulk-clearance
Content-Type: application/json

{ "userIds": ["u1", "u2", "u3"] }

Toggles the cleared flag for each user (records a cleared analytics action for every newly-cleared user). Returns { "updated": N }.

POST /api/admin/users/bulk-delete
Content-Type: application/json

{ "userIds": ["u1", "u2"] }

Deletes the listed users. The caller cannot include themselves; the request fails if it would remove every remaining administrator.

PATCH /api/admin/users/bulk-status
Content-Type: application/json

{ "userIds": ["u1", "u2"], "emailVerified": true }

Sets emailVerified to the given boolean for every user in the list.

Email logs

GET /api/admin/email-logs?limit=25&status=delivered&dateRange=7d&sort=desc

Response includes logs, total, summary (counts by status), and pagination.

Related

• API overview: base URL, authentication at a glance, and response conventions.
• API explorer: try administration endpoints live with the interactive Swagger console.