Box HTTP API
Last updated 2026-11-15
Everything below is served by the box itself, at the box's own origin
(https://pb-1234.plumbox.me, or a LAN address). There is no Plum server in the path.
This page covers what a third-party app needs. The machine-readable spec is at
GET /openapi.json (no auth): besides auth, drive, photos, shares, quota and storage it
documents /api/apps/*, /api/oauth/*, /api/events, /apps/{id}/svc/* and /dav/{id}/….
Authentication
| Credential | How | Where it works |
|---|---|---|
| Session cookie | session=…, set by the box's own login |
the web shell, panels |
| Personal access token | Authorization: Bearer plum_pat_… |
/api/* and /apps/{id}/svc/* |
| Basic | Authorization: Basic base64(<username>:plum_pat_…) |
/apps/{id}/svc/* (the username must own the token) |
An OAuth exchange hands you a token of the same plum_pat_… form, sent the same way — but it
expires after an hour and comes with a rotating refresh token (see OAuth below). A
box on core 1.11.3 or older still hands out tokens that never expire, and tokens issued before
boxes started expiring them keep working without expiry. Tokens the user creates by hand — in Settings, as a DAV Basic
password, or a device credential — are unchanged and long-lived.
Scopes: files:read, files:write, files:app, user:profile, service:call:<app_id>,
plus apps:install and apps:dev for developer tooling, and the legacy read / write /
admin. Enforcement is per request: read covers GET/HEAD/OPTIONS and write covers the rest;
files:write implies files:read; admin covers everything but is not obtainable through
OAuth. A user:profile token opens exactly GET /api/auth/me; a service:call:<id> token opens
that app's /svc/* and GET /api/apps/<id>/entitlement and nothing else; apps:install and
apps:dev tokens are confined to /api/apps/. A files:app token (OAuth only) opens the Drive
list/download/view/archive/versions/version-content, upload, mkdir, rename, move, save-text,
save-copy, restore-version and delete routes and the chunked /api/uploads/*, and only for paths
inside its own folder /Apps/<app display name>; every other route is 403. It neither implies
nor is implied by files:read / files:write — see
Companion apps.
401 or 403. An expired, revoked or unknown bearer token gets 401 with
WWW-Authenticate: Bearer error="invalid_token" — refresh it, or connect again. 403 means the
credential is fine and the request is not allowed: a scope the token lacks, or a path outside its
files:app folder. Refreshing does not change a 403.
Tokens
| Method | Path | Notes |
|---|---|---|
POST |
/api/auth/tokens |
session only. {"name","scopes":[…],"expiresInDays":null} → the token once, as token |
GET |
/api/auth/tokens |
list (prefixes only) |
DELETE |
/api/auth/tokens/{id} |
revoke |
GET |
/api/auth/me |
the signed-in user |
OAuth
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/authorize |
session | the consent screen (the portal redirects the user here) |
POST |
/api/oauth/authorize |
session | approve; returns {"code","redirect_uri","state"} |
POST |
/api/oauth/token |
none | exchange the code for tokens (PKCE is the proof), or a refresh token for a new pair |
GET |
/api/oauth/clients/{client_id} |
session | look up a registered client |
GET |
/.well-known/oauth-authorization-server |
none | RFC 8414 metadata: endpoints, grant_types_supported |
code_challenge_method=S256 is required, and codes live 5 minutes and are single-use.
grant_type is authorization_code or refresh_token ({"grant_type":"refresh_token",
"refresh_token","client_id"}); the endpoint takes JSON or form-encoded bodies. The reply is
{"access_token","token_type":"bearer","expires_in":3600,"refresh_token","scope"}, plus
"app_folder" when files:app was granted. Refresh tokens rotate — reusing an old one after a
60-second grace revokes the connection — and lapse after 90 days unused; 400
{"error":"invalid_grant"} means the user has to connect again. The metadata lists
grant_types_supported: ["authorization_code","refresh_token"]. Details and the client rules
are in Companion apps.
Apps
| Method | Path | What |
|---|---|---|
GET |
/api/apps |
installed apps (id, name, version, permissions, launch URL, update_available) |
GET |
/api/apps/overview |
the same with sizes, author, service state, publisherKid, countersignKind |
GET |
/api/apps/{id}/status |
service state: starting/ready/crashed/give_up/start_timeout/stopped, restarts, limits, memory_current, oom_kills |
POST |
/api/apps/{id}/restart |
restart the service |
GET |
/api/apps/{id}/logs[?follow=1] |
log snapshot, or SSE; a token needs apps:dev |
GET |
/api/apps/{id}/entitlement |
{"skus":[{sku,kind,expires_at,active}],"refreshed_at","stale"} |
POST |
/api/apps/entitlements/refresh |
refetch receipts now → {"ok":true,"receipts":n} |
GET |
/api/apps/{id}/permissions · POST |
what the user has enabled, and toggling it |
POST |
/api/apps/install[?app_id=…] |
install a signed .plu (multipart plu, or a raw zip body); needs apps:install |
POST |
/api/apps/store/install |
install from the store by {"store_app_id","version"} |
GET |
/api/apps/store/listing[?q=] |
the store catalog, annotated with what is installed |
GET |
/api/apps/store/compatible |
the "works with Plum Box" shelf (companion-only apps) |
POST |
/api/apps/{id}/update · PATCH /api/apps/{id}/settings |
update now; {"auto_update":bool} |
DELETE |
/api/apps/{id} · POST /api/apps/{id}/uninstall |
remove |
GET |
/api/apps/trust · PUT |
the box's trust level (owner) |
GET |
/api/apps/publishers |
trusted publisher keys and the embedded store key ids |
POST |
/api/apps/publishers/pair · /pair/confirm |
developer pairing (no auth: the 6-digit code the owner reads off the box is the proof) |
There is no per-app client endpoint — GET /api/oauth/clients/{client_id} is the only client
lookup.
Events
GET /api/events?kinds=drive,photos,apps:dev.jan.notes
Accept: text/event-stream
Server-sent events. kinds is a comma-separated filter (empty = everything) and accepts
<prefix>:* wildcards such as apps:*. Reconnect with the Last-Event-ID header (or
?last_id=); if too much was missed the box sends event: reset and you should re-read rather
than patch. Frames are id: <n> / event: <kind> / data: {"id","kind","at","payload"}, with a
: ping comment every 25 seconds and retry: 3000. At most 256 concurrent listeners per box.
Kinds published today: drive and photos (after any successful write under /api/drive/ or
/api/photos/, payload {"path","method"}), notification, and apps:<app_id> — both from a
service's control socket and from the box itself on install ({"type":"installed"}).
An app's own service
ANY /apps/{app_id}/svc/{path}
Proxied to the app's service with the caller's identity in X-Plum-* headers. A PAT needs the
exact service:call:<app_id> scope. See Service apps for the headers and
the failure codes.
Error shapes
Three, depending on the layer:
{"error": "forbidden", "message": "token lacks the apps:dev scope"} // /api/apps/*
{"error": "invalid_scope", "error_description": "…"} // OAuth
{"error": "app backend unavailable"} // the svc proxy
Developer-facing tools should read error and show message / error_description.