API guide

Every SubakoOS installation exposes a FastAPI interface for its own host. The public documentation is generated from the current main branch, so confirm behavior against the OpenAPI document served by your installed version.

The API is currently an implementation interface, not a separately versioned compatibility product. The /api/v1 prefix prevents accidental legacy routing, but does not yet promise long-term schema stability.

Base URLs

Use the same HTTPS origin as the web interface:

https://subako.example.com/api/v1

Interactive Swagger and ReDoc pages are available on an installed instance at /api/docs and /api/redoc. Its raw schema is /api/openapi.json.

Authentication

Login uses the host's PAM credentials. The login response provides short-lived access credentials and the application uses a secure refresh cookie in production. Preserve cookies when following browser-equivalent flows.

curl --fail-with-body \
  -c subako.cookies \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"REDACTED"}' \
  https://subako.example.com/api/v1/auth/login

Never put passwords in shell history, source files, or CI logs. For automation, use a protected secret input and review the exact authentication response for your installed release.

Authorization

Authentication alone does not grant every operation. Routes can require a module grant, an administrator role, or recent password confirmation. A 401 generally means the session is absent or expired; a 403 means the authenticated user lacks the required authorization.

Read example

The health endpoint is suitable for instance checks:

curl --fail-with-body \
  https://subako.example.com/api/v1/health

For protected routes, supply the access mechanism returned by login and retain the cookie jar when required:

curl --fail-with-body \
  -b subako.cookies \
  https://subako.example.com/api/v1/system/info

Mutation example

Mutation bodies are JSON unless the endpoint reference says otherwise. Host-changing routes may require administrator access and a recent-authentication header or challenge.

curl --fail-with-body \
  -X POST \
  -b subako.cookies \
  -H 'Content-Type: application/json' \
  -d '{"hostname":"subako-home"}' \
  https://subako.example.com/api/v1/system/hostname

Use the generated API reference to confirm the method, path, request schema, and responses before scripting an operation.

Errors

FastAPI validation failures use HTTP 422 with structured field details. Application errors commonly use JSON with a detail field. Preserve the HTTP status and response body in automation logs, but redact credentials and host-sensitive values.

WebSockets

SubakoOS uses WebSockets for live metrics, notifications, task output, container logs, and terminal sessions. WebSocket authentication is route-specific and follows the installed application's session rules. Browser developer tools and the frontend clients under frontend/src/lib/api are the best current examples.