Supervisor REST API

The ApexOS Supervisor exposes a REST API over HTTP on port 80 of the Supervisor container. From an app container the API is reachable at:

http://supervisor

Every app container is started with a SUPERVISOR_TOKEN environment variable containing its individual access token.

Authentication

Two header forms are accepted; the raw token is extracted from either:

Header	Format
Authorization	Bearer ${SUPERVISOR_TOKEN}
X-Supervisor-Token	${SUPERVISOR_TOKEN}

Requests without a token receive 401 Unauthorized. A token that does not grant access to the requested path receives 403 Forbidden.

A small set of paths skips token validation entirely (see Unauthenticated paths).

API versions

All endpoints in this reference are served at the root (v1). When the supervisor_v2_api feature flag is enabled, the same route set is additionally mounted under the /v2 prefix. The v2 tree renames the app endpoints from /addons/... to /apps/... and switches several payload keys from addons to apps (called out per endpoint). The v1 and v2 trees share the same security middleware.

Response envelope

JSON endpoints wrap their payload in a common envelope.

Success:

{
  "result": "ok",
  "data": { }
}

Error (HTTP status 400 by default):

{
  "result": "error",
  "message": "human readable error",
  "job_id": "optional, when a background job is involved",
  "error_key": "optional machine-readable error key",
  "extra_fields": { }
}

The data object is always present on success (empty {} for endpoints with no payload). Endpoints that return raw content bypass the envelope entirely:

• Log endpoints return text/plain (streamed).
• Icon/logo endpoints return image/png.
• Changelog/documentation endpoints return text/plain.
• Backup download returns application/tar.

Caller identities

The security middleware resolves the token to one of these identities:

Identity	Token source	Access
ApexOS Core	Core runtime token	Full access; sole caller allowed on sys_options and the ingress session endpoints
Host CLI plugin	CLI plugin token	Full access (no role filter applied)
Observer plugin	Observer plugin token	Only paths matching /{component}/info
App	Per-app SUPERVISOR_TOKEN	Governed by the role model below

Role model for apps

An app must declare API access to call role-gated endpoints; its assigned role then selects an allowed path set. Roles are cumulative in practice (each row of the table below extends the previous one only in the sense shown; manager does not include backup-only paths — it lists them explicitly).

Role	Allowed paths
default	/{component}/info (any info endpoint)
apexos	info endpoints, plus /core/* and /apexos/*
backup	info endpoints, plus /backups*
manager	info endpoints, plus: /addons* (except /addons/{app}/security), /audio/*, /auth/cache, /available_updates, /backups*, /cli/*, /core/*, /apexos/*, /dns/*, /docker/*, /jobs/*, /hardware/*, /host/*, /mounts*, /multicast/*, /network/*, /observer/*, /os/* (except /os/datadisk/wipe), /refresh_updates, /resolution/*, /security/*, /snapshots*, /store*, /supervisor/*
admin	Everything

Notes derived from the middleware tables:

• /addons/{app}/security and /os/datadisk/wipe are excluded from manager and therefore require admin.
• /auth/reset and /auth/list are not in any non-admin role set and require admin.
• On the /v2 tree, manager gains /reload_updates and loses the deprecated /available_updates, /refresh_updates, and /snapshots* entries.

Token bypass paths (any installed app)

Regardless of role, any installed app's token is accepted on:

• /addons/self/{action} — except security and update (v2: /apps/self/{action})
• /addons/self/options/config (v2: /apps/self/options/config)
• /info
• /services*
• /discovery*
• /auth

Handlers behind these paths apply their own finer-grained checks (e.g. /auth requires the app to declare auth-API access; /services enforces per-service roles; several /discovery reads are core-only).

Core-only paths

POST /addons/{app}/sys_options (v2: /apps/{app}/sys_options) is rejected for every caller except ApexOS Core, before role evaluation.

Unauthenticated paths

Token validation is skipped for:

• /core/api/*, /core/websocket, /apexos/api/*, /apexos/websocket — the Core API proxy performs its own token check
• /supervisor/ping
• /ingress/{token}/{path} — protected by ingress session cookies instead
• Frontend asset paths: /app/*.(js|gz|json|map|woff2) and /(store/)?addons/{slug}/(logo|icon)

On the /v2 tree only the ingress path and /store/apps/{slug}/(logo|icon) are exempt — the Core API proxy paths under /v2 require a valid token with the apexos role or higher.

Always-blocked paths

/core/api/supervisor/* and /apexos/api/supervisor/* (also under /v2) are unconditionally rejected with 403, preventing the Core API proxy from being used to loop back into the Supervisor.

Additionally, a request filter rejects (HTTP 400) paths and query strings containing common exploit patterns (path traversal, script injection, SQL injection fragments), and the whole API returns an error while the Supervisor is not in the startup, running, or freeze state.

Background jobs

Several long-running operations (backup, restore, update, install) accept a "background": true body flag. When set, the call returns immediately with {"job_id": "..."} in data; progress can be tracked via the jobs endpoints. Without the flag the call blocks until completion (and still reports the job_id).

Endpoint groups

Group	Reference
Core runtime lifecycle	endpoints-core
Apps (add-ons)	endpoints-addons
Operating system	endpoints-os
Network	endpoints-network
Backups	endpoints-backups
Store	endpoints-store
Host	endpoints-host
Supervisor, plugins & misc	endpoints-misc
Core API / WebSocket proxy	websocket-proxy