Admin Endpoints

Admin endpoints live under /api/admin/* and require a PAT whose user has the admin or owner role. Transfer of the owner role is restricted to the current owner. The health check requires no authentication.

Server Stats

GET /api/admin/stats
Authorization: Bearer club_pat_...

Returns server uptime, resource counts (packages, versions, users), disk usage, and information about the configured storage backends.

Also returns a database block with the size the database engine reports for itself, how much of that space is reclaimable by a VACUUM, and a breakdown of the largest tables and indexes. This is the engine’s own accounting, so it differs slightly from the on-disk disk.database figure (which also covers SQLite’s -wal and -shm sidecars). Backends that cannot report these numbers return {"available": false}.

---

User Management

List Users

GET /api/admin/users?email=<filter>&page=<n>
Authorization: Bearer club_pat_...

Query	Description
email	Partial/case-insensitive email match
page	Page number (1-indexed)

Get a User

GET /api/admin/users/<userId>
Authorization: Bearer club_pat_...

Create a User

POST /api/admin/users
Authorization: Bearer club_pat_...
Content-Type: application/json

{
  "email": "newuser@example.com",
  "displayName": "New User",
  "role": "member",
  "mode": "invite",
  "expiresInHours": 72
}

Field	Type	Required	Description
email	string	yes	Login email (must be unique)
displayName	string	yes	Human-readable name
role	string	no	admin, member, or viewer (legacy editor also accepted; normalised to member). Defaults to viewer
mode	string	no	password generates a one-time password; invite issues an invite URL. Defaults to password
expiresInHours	integer	no	Only used for invite mode. Defaults to 168 (7 days)

Response: 201 Created — returns the user plus either generatedPassword (for password mode) or inviteUrl (for invite mode).

Update a User

PUT /api/admin/users/<userId>
Authorization: Bearer club_pat_...
Content-Type: application/json

{
  "role": "admin",
  "displayName": "Jane D.",
  "isActive": false
}

All fields are optional; only included fields are changed. Deactivating a user disables their sessions and PATs immediately.

Delete a User

DELETE /api/admin/users/<userId>
Authorization: Bearer club_pat_...

Reset a User’s Password

POST /api/admin/users/<userId>/reset-password
Authorization: Bearer club_pat_...
Content-Type: application/json

{ "password": "optional-new-password" }

If password is omitted, the server generates one and returns it in the response. All existing sessions for the user are revoked.

---

Ownership Transfer

POST /api/admin/transfer-ownership
Authorization: Bearer club_pat_...
Content-Type: application/json

{ "email": "new-owner@example.com" }

Only the current owner can call this. The target user becomes the new owner; the previous owner is demoted to admin.

---

Package Removal

Delete a Package

DELETE /api/admin/packages/<package>
Authorization: Bearer club_pat_...

Removes the package and every version, including blob storage and the search index.

If any public package depends on this one, the call is refused until the caller explicitly accepts the breakage. Deletion cannot be undone the way a visibility flip can, so the check runs first.

Delete a Version

DELETE /api/admin/packages/<package>/versions/<version>
Authorization: Bearer club_pat_...

Removes a single version and its tarball.

Danger

Both operations are permanent and will break any lockfile that pinned the deleted version. Prefer retracting or discontinuing when possible.

---

Public Packages

The server-wide half of the public packages switch. Server admin only.

GET /api/admin/public-packages
Authorization: Bearer club_pat_...

{
  "permittedByEnvironment": true,
  "enabled": false,
  "requiresServerAdmin": true,
  "totalPackages": 42,
  "publicPackages": 0
}

permittedByEnvironment reflects PUBLIC_PACKAGES_ENABLED in the server environment. When it is false the deployment forbids the feature outright and the toggle below cannot help.

PUT /api/admin/public-packages
Authorization: Bearer club_pat_...
Content-Type: application/json

{
  "enabled": true
}

Returns 403 when the environment gate is off, naming the variable to set. Both directions are written to the audit log.

Caution

Setting enabled back to false is a kill switch: every public package requires credentials again on the next request, with no per-package state changed. It does not recall anything already downloaded.

---

Scoring Control

Re-queue Pana Analysis

POST /api/admin/packages/<package>/versions/<version>/rescore
Authorization: Bearer club_pat_...

Queues the version for a fresh pana run. Response: 200 OK.

Score Any Unscored Versions

POST /api/admin/sdk/score-remaining
Authorization: Bearer club_pat_...

Kicks off scoring for every package version that is missing a report.

Scoring Logs

GET    /api/admin/sdk/scoring-logs
DELETE /api/admin/sdk/scoring-logs

GET returns recent scoring job logs. DELETE clears them.

---

SDK Management

club bundles a pana-capable Dart/Flutter SDK and lets admins manage which version is used.

Discover Releases

GET /api/admin/sdk/releases?channel=<stable|beta|dev>
Authorization: Bearer club_pat_...

Lists available Dart/Flutter SDK releases for a channel.

Installed SDKs

GET  /api/admin/sdk/installs
POST /api/admin/sdk/installs

POST installs a new SDK:

{ "version": "3.4.0", "channel": "stable" }

Install Progress

GET /api/admin/sdk/installs/<id>/progress
Authorization: Bearer club_pat_...

Returns the current download/extract progress for an install.

Set Default / Rebuild / Remove

POST   /api/admin/sdk/installs/<id>/set-default
POST   /api/admin/sdk/installs/<id>/rebuild
DELETE /api/admin/sdk/installs/<id>

SDK Settings

GET /api/admin/sdk/settings
PUT /api/admin/sdk/settings

Read or update global SDK scoring configuration.

Platform Info

GET /api/admin/sdk/platform
Authorization: Bearer club_pat_...

Returns the server’s detected OS/architecture so the UI can pick the right SDK builds.

---

Dartdoc

Regenerate Documentation

POST /api/admin/packages/<package>/regenerate-docs
Authorization: Bearer club_pat_...

Queues dartdoc regeneration for the package’s latest version.

---

Health Check

GET /api/v1/health

No authentication required. Use for load-balancer and uptime monitoring.

Response: 200 OK (healthy) or 503 Service Unavailable (degraded):

{
  "status": "ok",
  "checks": {
    "metadata_store": { "status": "ok", "latencyMs": 2 },
    "blob_store":     { "status": "ok", "latencyMs": 5 },
    "search_index":   { "status": "ok", "latencyMs": 1 }
  },
  "version": "1.0.0",
  "timestamp": "2026-04-09T10:00:00.000Z"
}

Field	Description
status	ok or degraded
checks.*.status	ok, error, or (search index only) initializing
checks.*.latencyMs	Probe latency
checks.*.message	Error detail when unhealthy
version	Server version
timestamp	ISO 8601 check time

Tip

Use the per-component checks object to identify which backend is degraded.