TrixOS API

Everything the TrixOS panel does goes through this API: the web interface uses exactly these endpoints. This reference is generated from the code of release 0.9.0 and lists all 177 endpoints of the native API, plus the TenantOS-compatible and internal ones.

Base URL

Each installation serves its own API. All native endpoints live under /api/v1 of your panel:

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

Your panel also serves this specification itself, for the version it runs: Swagger UI at /api/docs and the JSON at /api/docs/json, for signed-in admins (an admin API token works too; TRIXOS_API_DOCS=publicopens them to everyone, off turns them off). The file for this reference is openapi.json.

Authentication

API tokens

Scripts and other systems use API tokens. Create one under Users → API tokens in the panel or with POST /users/{id}/tokens, and send it in every request:

Authorization: Bearer 12|kD8s0Vt2…

A token is <id>|<secret>, the same format TenantOS used. The secret is shown once; only its hash is stored. A token can expire, can be limited to source IP addresses, and never has more rights than its user. Its scopes narrow it further:

• *
• servers:read
• servers:power
• servers:console
• servers:provision
• servers:write
• ipam:read
• ipam:write
• users:read
• users:write
• admin

* means everything the token’s user may do. Scopes are enforced on every request: a token without the scope for an endpoint gets 403, and endpoints outside these scopes need admin.

Browser sessions

The web interface signs in with POST /auth/login, which sets an httpOnly, SameSite=Strict session cookie. With two-factor authentication on, POST /auth/mfa completes the sign-in. Requests that change something must send the header X-Requested-With: trixos; it protects cookie sessions against cross-site requests.

Requests and responses

Requests and responses are JSON, and every request is validated against the schema shown in this reference. Most lists return an array; paged lists such as GET /servers return {"data": [...], "total": n, "page": 1, "perPage": 50} and take page and perPage.

Errors

Errors have one shape and a stable code:

{
  "error": {
    "code": "LOCKED",
    "message": "Another destructive job is already running for this server.",
    "details": null
  }
}

Rate limits

1,200 requests per minute per token, or per IP address without a token. Sign-in is limited to 10 attempts per minute. Over the limit, the API answers 429.

Hardware actions and jobs

Anything that touches a server’s hardware runs as a job:

1. Destructive actions (power off, reset, cycle, reinstall, rescue, disk wipe, password reset, port shutdown) need the server’s hostname in the body as "confirm": "web-01". Endpoints that need it are marked in this reference.
2. The API answers 202 with the job. Follow it with GET /jobs/{id} or the job websocket.
3. A job ends as success, failed or cancelled. Only one hardware job per server runs at a time; a second one gets 409 LOCKED.
4. While the panel is in dry-run mode, jobs run through all steps without touching hardware and carry dryRun: true.

Websockets

Versions

The API is versioned with TrixOS itself: the spec’s version is the release. Changes to endpoints are listed in the changelog.

Sections