Panel HTTP API#

The panel's browser uses a same-origin, cookie-authenticated HTTP API on the panel URL (default http://127.0.0.1:20772). This is the panel's internal application API and can change between panel releases. There is no panel API-key authentication.

The source of truth is src/Web/Program.cs and BundleToolsEndpoints.cs. Request records live in those files and src/Shared. Match the source revision in sources.json when developing an integration.

Sessions, CSRF and response shapes#

GET /api/session returns {authenticated, username, permissions, csrf} and issues the CSRF cookie. Every POST, including login and setup, requires the returned token in X-CSRF together with its cookie. POST /api/login takes {username, password, remember} and creates the replay-panel-session HttpOnly cookie. POST /api/logout ends it. A normal session expires after four hours without sliding renewal; remember-me uses a 30-day persistent authentication ticket. Account changes can revoke a session through its security stamp.

Most mutations return a Reply: {ok, error?, status?, lines?}. Some data routes unwrap JSON from lines[0] and return that data directly. GET /api/status returns a Reply containing status; do not assume every GET has that shape.

Errors use localization keys such as csrf.invalid, update.busy or bundleTools.disabled; display them through the panel's translation layer. HTTPS remote access requires the proxy configuration. Do not expose the loopback service by changing a bind address without configuring trusted proxies and allowed hosts.

Browser example#

Run this from a same-origin panel integration. The user supplies their own credentials through its login UI.

async function session() {
  const response = await fetch('/api/session', { credentials: 'same-origin' });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}
async function post(path, body) {
  const { csrf } = await session();
  const response = await fetch(path, {
    method: 'POST', credentials: 'same-origin',
    headers: { 'Content-Type': 'application/json', 'X-CSRF': csrf },
    body: JSON.stringify(body)
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  return response.json();
}
// After the user logs in:
const state = await (await fetch('/api/status')).json();
console.log(state.status);
// With console.write permission, a read-only game console command:
// await post('/api/command', { text: 'bundles' });

Core route reference#

Use users and permissions for the complete permission model and administrator safeguards. Read the exact route handler before implementing a mutating integration; server configuration, path validation and permission rules include checks beyond HTTP authorization.

Updates and asynchronous jobs#

Panel update routes are GET /api/updates and POST /api/updates/{check,download,cancel,apply}. Server updates use GET /api/server-updates and POST /api/server-updates/{check,download,apply,cancel} with an optional {target}. They require settings.write; download/apply also require users.manage. Inspect returned job status rather than treating acceptance as completion. While a panel update is applying, authenticated POST operations are refused with 409 update.busy. See updates and server updates for backups and rollback.

Experimental bundle tools#

These routes require the feature master switch and individual permissions. Source builds execute trusted project code on the host. See Bundle Tools before enabling them.

projects/delivery and packages/set currently return 409 bundleTools.workflow; use the configured review workflow. The detailed JSON payloads are defined by the supervisor's BundleTools handlers and the panel UI at the recorded source commit. Account tokens are encrypted on the supervisor and never returned to the browser.

Setup routes#

First-time setup uses the local setup key and is rate limited. POST routes: /api/setup/validate, /install, /finish, /pick, /pick-status, /job, /cancel. The setup document contains {key,dashboardName,username,password,confirmation,locale,serverRoot,backend}; job/pick-status/cancel use {key}. The directory picker is available only for a direct loopback request. GET /api/setup/console reports setup-console availability; it does not replace the key requirement. Follow the setup UI and installation guide for supported ordering and validation.