{ "openapi": "3.0.3", "info": { "title": "TrixOS API", "version": "0.9.0", "description": "Native TrixOS API (/api/v1). TenantOS-compatible endpoints live under /api/*." }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "| API token" } }, "schemas": {} }, "paths": { "/api/v1/auth/login": { "post": { "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 200 }, "password": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "username", "password" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/mfa": { "post": { "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/me": { "get": { "tags": [ "auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/totp/setup": { "post": { "tags": [ "auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/totp/enable": { "post": { "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "minLength": 16, "maxLength": 64 }, "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "secret", "code" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/totp/disable": { "post": { "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers": { "get": { "tags": [ "servers" ], "parameters": [ { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "tag", "required": false }, { "schema": { "type": "integer" }, "in": "query", "name": "ownerId", "required": false }, { "schema": { "type": "string", "enum": [ "on", "off", "unknown" ] }, "in": "query", "name": "power", "required": false }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "maintenance", "required": false }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "protected", "required": false }, { "schema": { "type": "string", "maxLength": 4000, "pattern": "^\\d+(,\\d+)*$" }, "in": "query", "name": "ids", "required": false }, { "schema": { "anyOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, { "type": "string", "enum": [ "none" ] } ] }, "in": "query", "name": "siteId", "required": false }, { "schema": { "anyOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, { "type": "string", "enum": [ "none" ] } ] }, "in": "query", "name": "rackId", "required": false }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "traffic", "required": false }, { "schema": { "default": "id", "type": "string", "enum": [ "id", "hostname", "servername", "os", "createdAt", "powerStatus" ] }, "in": "query", "name": "sort", "required": false }, { "schema": { "default": "asc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "dir", "required": false }, { "schema": { "default": 1, "type": "integer", "minimum": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "perPage", "required": false } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "servers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string", "minLength": 1, "maxLength": 253 }, "servername": { "default": "", "type": "string", "maxLength": 253 }, "ownerId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "type": { "default": "dedicated", "type": "string", "enum": [ "dedicated", "virtual", "external" ] }, "siteId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bootMode": { "default": "auto", "type": "string", "enum": [ "auto", "legacy", "uefi" ] }, "pxeMac": { "nullable": true, "type": "string", "pattern": "^([0-9a-fA-F]{2}[:-]){5}[0-9a-fA-F]{2}$" }, "description": { "default": "", "type": "string", "maxLength": 5000 }, "tags": { "default": [], "type": "array", "items": { "type": "string", "maxLength": 64 } }, "bmc": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ipmi", "redfish", "idrac", "ilo", "supermicro", "xcc" ] }, "host": { "type": "string", "minLength": 1, "maxLength": 255 }, "port": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 65535 }, "username": { "default": "", "type": "string", "maxLength": 128 }, "password": { "type": "string", "maxLength": 256 }, "vendor": { "default": "generic", "type": "string", "maxLength": 32 }, "consoleProvider": { "nullable": true, "type": "string", "maxLength": 32, "enum": [ "auto", "hpe", "dell", "supermicro", "lenovo" ], "description": "Web BMC provider; missing or unknown = auto (TenantOS names ilo, hp, idrac, xcc are mapped)" }, "options": { "type": "object", "additionalProperties": {} }, "ipmitoolFlags": { "type": "string", "maxLength": 200 }, "installPowerAction": { "type": "string", "enum": [ "cycle", "reset", "off_on" ] }, "consoleMode": { "type": "string", "enum": [ "all", "kvm", "sol" ] }, "consoleFakeDate": { "nullable": true, "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "clientUsername": { "nullable": true, "type": "string", "maxLength": 64 }, "clientPassword": { "nullable": true, "type": "string", "maxLength": 128 }, "showCredentials": { "type": "boolean" }, "consoleKvmType": { "type": "string", "enum": [ "auto", "html5", "java" ] }, "consoleJavaVersion": { "type": "string", "enum": [ "8", "11", "17", "auto" ] }, "consoleBrowser": { "type": "string", "enum": [ "chromium", "chromium-legacy-tls" ] }, "consoleUserAccount": { "type": "string", "enum": [ "stored", "temporary", "client" ] }, "consoleWebPrivilege": { "anyOf": [ { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 4 ] } ] }, "consoleLoginBar": { "type": "string", "enum": [ "off", "admins", "all" ] }, "webConsoleEnabled": { "type": "boolean" } }, "required": [ "type", "host" ] }, "rackId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "rackPosition": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 60 }, "rackHeightU": { "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "hostname" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/tags": { "get": { "tags": [ "servers" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}": { "get": { "tags": [ "servers" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "tags": [ "servers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string", "minLength": 1, "maxLength": 253 }, "servername": { "type": "string", "maxLength": 253 }, "description": { "type": "string", "maxLength": 5000 }, "os": { "nullable": true, "type": "string", "maxLength": 200 }, "ownerId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "siteId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bootMode": { "type": "string", "enum": [ "auto", "legacy", "uefi" ] }, "type": { "type": "string", "enum": [ "dedicated", "virtual", "external" ] }, "ipxeBiosFile": { "nullable": true, "type": "string", "enum": [ "undionly.kkpxe", "undionly.kpxe" ] }, "ipxeEfiFile": { "nullable": true, "type": "string", "enum": [ "ipxe.efi", "snponly.efi" ] }, "pxeMac": { "nullable": true, "type": "string", "pattern": "^([0-9a-fA-F]{2}[:-]){5}[0-9a-fA-F]{2}$" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "customFields": { "type": "object", "additionalProperties": {} }, "suspended": { "type": "boolean" }, "rackId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "rackPosition": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 60 }, "rackHeightU": { "type": "integer", "minimum": 1, "maximum": 60 } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "servers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/protection": { "post": { "tags": [ "servers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "protected": { "type": "boolean" }, "confirm": { "type": "string" } }, "required": [ "protected" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/bmc": { "put": { "tags": [ "servers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ipmi", "redfish", "idrac", "ilo", "supermicro", "xcc" ] }, "host": { "type": "string", "minLength": 1, "maxLength": 255 }, "port": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 65535 }, "username": { "default": "", "type": "string", "maxLength": 128 }, "password": { "type": "string", "maxLength": 256 }, "vendor": { "default": "generic", "type": "string", "maxLength": 32 }, "consoleProvider": { "nullable": true, "type": "string", "maxLength": 32, "enum": [ "auto", "hpe", "dell", "supermicro", "lenovo" ], "description": "Web BMC provider; missing or unknown = auto (TenantOS names ilo, hp, idrac, xcc are mapped)" }, "options": { "type": "object", "additionalProperties": {} }, "ipmitoolFlags": { "type": "string", "maxLength": 200 }, "installPowerAction": { "type": "string", "enum": [ "cycle", "reset", "off_on" ] }, "consoleMode": { "type": "string", "enum": [ "all", "kvm", "sol" ] }, "consoleFakeDate": { "nullable": true, "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "clientUsername": { "nullable": true, "type": "string", "maxLength": 64 }, "clientPassword": { "nullable": true, "type": "string", "maxLength": 128 }, "showCredentials": { "type": "boolean" }, "consoleKvmType": { "type": "string", "enum": [ "auto", "html5", "java" ] }, "consoleJavaVersion": { "type": "string", "enum": [ "8", "11", "17", "auto" ] }, "consoleBrowser": { "type": "string", "enum": [ "chromium", "chromium-legacy-tls" ] }, "consoleUserAccount": { "type": "string", "enum": [ "stored", "temporary", "client" ] }, "consoleWebPrivilege": { "anyOf": [ { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 4 ] } ] }, "consoleLoginBar": { "type": "string", "enum": [ "off", "admins", "all" ] }, "webConsoleEnabled": { "type": "boolean" } }, "required": [ "type", "host" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/maintenance": { "put": { "tags": [ "servers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "reason": { "default": "", "type": "string", "maxLength": 500 } }, "required": [ "enabled" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/power/refresh": { "post": { "tags": [ "power" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serverIds": { "maxItems": 1000, "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } } } } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/power": { "get": { "tags": [ "power" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "power" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "setPowerOn", "setPowerOff", "setPowerSoft", "setPowerReset", "setPowerCycle", "setBmcReset" ] }, "confirm": { "type": "string" } }, "required": [ "action" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/bmc/command": { "post": { "summary": "Execute an IPMI command", "tags": [ "power" ], "description": "The \"Execute IPMI command\" dialog of the IPMI device (admins). Plain ipmitool words without options; the connection comes from the server's IPMI device. Status and information commands (power status, chassis status, sel list last 20, sdr list all|full|event, fru print, bmc info|guid|selftest, session info active|all, user list, lan print) run right away. power on|off|soft|reset|cycle|diag, chassis bootdev … and chassis identify change the server: they follow the protected, maintenance and dry-run rules and run as an audited `bmc_command` job (since 0.8.0 without a typed hostname; `confirm` is accepted and ignored). Everything else (user set, lan set, raw, mc reset, sol set, channel …) is refused. IPMI devices only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "string", "minLength": 1, "maxLength": 500 }, "confirm": { "type": "string" } }, "required": [ "command" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/bmc/reveal-password": { "post": { "summary": "Show the stored BMC password", "tags": [ "servers" ], "description": "The password of the BMC account stored in the IPMI device, in plain text (the eye button in Configuration → IPMI device). Admins only; every read is written to the audit log (`bmc.password.reveal`), limited to 10 per minute, never cached.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/sensors/live": { "get": { "tags": [ "monitoring" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/reinstall": { "post": { "tags": [ "provisioning" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "diskLayoutId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "rootPassword": { "nullable": true, "type": "string", "minLength": 8, "maxLength": 128 }, "sshKeyIds": { "default": [], "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "sshKeys": { "default": [], "type": "array", "items": { "type": "string", "maxLength": 16000 } }, "scriptIds": { "default": [], "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "hostname": { "nullable": true, "type": "string", "maxLength": 253 }, "bootMode": { "nullable": true, "type": "string", "enum": [ "auto", "legacy", "uefi" ] }, "confirm": { "type": "string" } }, "required": [ "profileId" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/hardware-discover": { "post": { "summary": "Discover the hardware without a reboot (shell command or running rescue system)", "tags": [ "provisioning" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "via": { "default": "shell", "type": "string", "enum": [ "shell", "rescue" ] } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/hardware-discover/options": { "get": { "summary": "Hardware discovery options for a server (PXE, shell command, running rescue system)", "tags": [ "provisioning" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/rescue": { "post": { "tags": [ "provisioning" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "rootPassword": { "nullable": true, "type": "string", "minLength": 8, "maxLength": 128 }, "sshKeyIds": { "default": [], "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "sshKeys": { "default": [], "type": "array", "items": { "type": "string", "maxLength": 16000 } }, "wipeMethod": { "type": "string", "enum": [ "fast", "secure", "blkdiscard", "nvme", "shred", "zero" ] }, "bootMode": { "nullable": true, "type": "string", "enum": [ "auto", "legacy", "uefi" ] }, "confirm": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/hardware-collect": { "post": { "tags": [ "provisioning" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "rootPassword": { "nullable": true, "type": "string", "minLength": 8, "maxLength": 128 }, "sshKeyIds": { "default": [], "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "sshKeys": { "default": [], "type": "array", "items": { "type": "string", "maxLength": 16000 } }, "wipeMethod": { "type": "string", "enum": [ "fast", "secure", "blkdiscard", "nvme", "shred", "zero" ] }, "bootMode": { "nullable": true, "type": "string", "enum": [ "auto", "legacy", "uefi" ] }, "confirm": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/disk-wipe": { "post": { "tags": [ "provisioning" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "rootPassword": { "nullable": true, "type": "string", "minLength": 8, "maxLength": 128 }, "sshKeyIds": { "default": [], "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "sshKeys": { "default": [], "type": "array", "items": { "type": "string", "maxLength": 16000 } }, "wipeMethod": { "type": "string", "enum": [ "fast", "secure", "blkdiscard", "nvme", "shred", "zero" ] }, "bootMode": { "nullable": true, "type": "string", "enum": [ "auto", "legacy", "uefi" ] }, "confirm": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/password-reset": { "post": { "tags": [ "provisioning" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "rootPassword": { "nullable": true, "type": "string", "minLength": 8, "maxLength": 128 }, "sshKeyIds": { "default": [], "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "sshKeys": { "default": [], "type": "array", "items": { "type": "string", "maxLength": 16000 } }, "wipeMethod": { "type": "string", "enum": [ "fast", "secure", "blkdiscard", "nvme", "shred", "zero" ] }, "bootMode": { "nullable": true, "type": "string", "enum": [ "auto", "legacy", "uefi" ] }, "confirm": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/provisioning/cancel": { "post": { "tags": [ "provisioning" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "powerReset": { "default": false, "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/jobs": { "get": { "tags": [ "jobs" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/console": { "post": { "summary": "Open a console", "tags": [ "console" ], "description": "One-time console token (60 s, bound to the user, server and IP) for `sol` (serial), `vnc` (KVM) or `web` (the BMC web UI). Open `/console/{token}?m={mode}` in a window; the page connects to `/api/v1/ws/console/{token}`. The BMC web UI is for admins, and for owners only when the IPMI device gives users an account of their own (temporary BMC user or client account).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "default": "sol", "type": "string", "enum": [ "sol", "vnc", "web" ] } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/ips": { "get": { "tags": [ "ipam" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "ipam" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subnetId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "ips": { "minItems": 1, "maxItems": 256, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "ignoreLocation": { "default": false, "type": "boolean" } }, "required": [ "subnetId", "ips" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "ipam" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ips": { "minItems": 1, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "ips" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/ips/{assignmentId}/primary": { "post": { "tags": [ "ipam" ], "parameters": [ { "schema": { "type": "integer" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "integer" }, "in": "path", "name": "assignmentId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/inventory": { "get": { "tags": [ "servers" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "put": { "tags": [ "servers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "component": { "type": "string", "enum": [ "cpu", "memory", "disk", "mainboard", "nic", "gpu", "psu", "other" ] }, "model": { "type": "string", "maxLength": 200 }, "value": { "type": "string", "maxLength": 100 }, "unit": { "default": "", "type": "string", "maxLength": 20 }, "serial": { "nullable": true, "type": "string", "maxLength": 100 }, "details": { "default": {}, "type": "object", "additionalProperties": {} } }, "required": [ "component", "model", "value" ] } } }, "required": [ "items" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "servers" ], "parameters": [ { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] }, "in": "query", "name": "nics", "required": false }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] }, "in": "query", "name": "smart", "required": false }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] }, "in": "query", "name": "firmware", "required": false }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/smart": { "get": { "tags": [ "servers" ], "parameters": [ { "schema": { "default": 100, "type": "integer", "minimum": 0, "maximum": 1000 }, "in": "query", "name": "history", "required": false }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/smart/{reportId}": { "get": { "tags": [ "servers" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "reportId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/inventory/firmware": { "post": { "tags": [ "servers" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/inventory/bmc": { "post": { "summary": "Read the hardware from the BMC (read-only) into the inventory", "tags": [ "servers" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/inventory/items/{itemId}": { "delete": { "tags": [ "servers" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "itemId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/inventory/nics/{nicId}": { "delete": { "tags": [ "servers" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "nicId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/notes": { "get": { "tags": [ "servers" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "servers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 20000 }, "sticky": { "default": false, "type": "boolean" } }, "required": [ "body" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/notes/{noteId}": { "delete": { "tags": [ "servers" ], "parameters": [ { "schema": { "type": "integer" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "integer" }, "in": "path", "name": "noteId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/switch-ports": { "get": { "tags": [ "network" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/graphs/bandwidth": { "get": { "tags": [ "monitoring" ], "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/graphs/sensors": { "get": { "tags": [ "monitoring" ], "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/audit": { "get": { "tags": [ "audit" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/ip-views": { "get": { "tags": [ "ipam" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/jobs": { "get": { "tags": [ "jobs" ], "parameters": [ { "schema": { "type": "string", "enum": [ "queued", "running", "success", "failed", "cancelled" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "enum": [ "power", "bmc_command", "reinstall", "rescue", "hardware_collect", "hardware_discover", "firmware_update", "disk_wipe", "password_reset", "switch_port", "outlet_power", "agent_install" ] }, "in": "query", "name": "type", "required": false }, { "schema": { "type": "integer" }, "in": "query", "name": "serverId", "required": false }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/jobs/{id}": { "get": { "tags": [ "jobs" ], "parameters": [ { "schema": { "default": 0, "type": "integer" }, "in": "query", "name": "afterLogId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/jobs/{id}/cancel": { "post": { "tags": [ "jobs" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/users": { "get": { "tags": [ "users" ], "parameters": [ { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "search", "required": false } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^[A-Za-z0-9._@-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "nullable": true, "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "nullable": true, "type": "string", "minLength": 10, "maxLength": 200 }, "role": { "default": "user", "type": "string", "enum": [ "admin", "reseller", "user" ] }, "parentId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "canCreateSubUsers": { "type": "boolean" }, "description": { "nullable": true, "type": "string", "maxLength": 2000 } }, "required": [ "username", "name" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/users/{id}": { "get": { "tags": [ "users" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "tags": [ "users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "nullable": true, "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "type": "string", "minLength": 10, "maxLength": 200 }, "currentPassword": { "type": "string", "maxLength": 500 }, "role": { "type": "string", "enum": [ "admin", "reseller", "user" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "timezone": { "type": "string", "maxLength": 64 }, "language": { "type": "string", "maxLength": 15 }, "allowedHosts": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "canCreateSubUsers": { "type": "boolean" }, "description": { "nullable": true, "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "users" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/users/{id}/tokens": { "get": { "tags": [ "tokens" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "tokens" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "default": [ "*" ], "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "*", "servers:read", "servers:power", "servers:console", "servers:provision", "servers:write", "ipam:read", "ipam:write", "users:read", "users:write", "admin" ] } }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "allowedHosts": { "default": [], "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "name" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/users/{id}/tokens/{tokenId}": { "delete": { "tags": [ "tokens" ], "parameters": [ { "schema": { "type": "integer" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "integer" }, "in": "path", "name": "tokenId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/users/{id}/ssh-keys": { "get": { "tags": [ "users" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "publicKey": { "type": "string", "minLength": 20, "maxLength": 16000 }, "description": { "nullable": true, "type": "string", "maxLength": 500 } }, "required": [ "name", "publicKey" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/users/{id}/ssh-keys/{keyId}": { "delete": { "tags": [ "users" ], "parameters": [ { "schema": { "type": "integer" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "integer" }, "in": "path", "name": "keyId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/users/{id}/login-history": { "get": { "tags": [ "users" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/users/{id}/server-permissions": { "get": { "tags": [ "users" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "put": { "tags": [ "users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serverId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "read", "power", "console", "provision", "ipam", "write" ] } } }, "required": [ "serverId", "permissions" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/subnets": { "get": { "tags": [ "ipam" ], "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "parentId", "required": false }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "roots", "required": false }, { "schema": { "anyOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, { "type": "string", "enum": [ "none" ] } ] }, "in": "query", "name": "siteId", "required": false } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "ipam" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cidr": { "type": "string", "minLength": 3, "maxLength": 64 }, "gateway": { "nullable": true, "type": "string", "maxLength": 64 }, "parentId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "ownerId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "siteId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "dnsResolvers": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "description": { "type": "string", "maxLength": 500 }, "vlan": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 4094 }, "generateIps": { "type": "boolean" } }, "required": [ "cidr" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/subnets/{id}": { "get": { "tags": [ "ipam" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "tags": [ "ipam" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gateway": { "nullable": true, "type": "string", "maxLength": 64 }, "ownerId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "dnsResolvers": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "description": { "type": "string", "maxLength": 500 }, "vlan": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 4094 }, "reserved": { "type": "boolean" }, "siteId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "applyToChildren": { "default": true, "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "ipam" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/subnets/{id}/split": { "post": { "tags": [ "ipam" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prefix": { "type": "integer", "minimum": 1, "maximum": 128 }, "limit": { "default": 4096, "type": "integer", "minimum": 1, "maximum": 65536 } }, "required": [ "prefix" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/subnets/{id}/free": { "get": { "tags": [ "ipam" ], "parameters": [ { "schema": { "default": 256, "type": "integer", "minimum": 1, "maximum": 5000 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/ips/{ip}": { "patch": { "tags": [ "ipam" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "nullable": true, "type": "string", "maxLength": 500 }, "reserved": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "in": "path", "name": "ip", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/rdns/{ip}": { "put": { "tags": [ "ipam" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ptr": { "type": "string", "maxLength": 253, "pattern": "^[A-Za-z0-9.-]*$" } }, "required": [ "ptr" ] } } } }, "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "in": "path", "name": "ip", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/sites": { "get": { "tags": [ "network" ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "network" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "hostname": { "nullable": true, "type": "string", "maxLength": 255 }, "description": { "nullable": true, "type": "string", "maxLength": 500 }, "address": { "type": "string", "maxLength": 500 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/switches": { "get": { "tags": [ "network" ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "network" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "host": { "type": "string", "minLength": 1, "maxLength": 255 }, "vendor": { "default": "generic", "type": "string", "maxLength": 32 }, "siteId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "features": { "default": [ "bw_collection" ], "type": "array", "items": { "type": "string", "enum": [ "bw_collection", "port_admin", "poe" ] } }, "meta": { "default": {}, "type": "object", "additionalProperties": {} }, "credentials": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "string", "enum": [ "2c" ] }, "community": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "version", "community" ] }, { "type": "object", "properties": { "version": { "type": "string", "enum": [ "3" ] }, "user": { "type": "string", "minLength": 1, "maxLength": 64 }, "authProtocol": { "type": "string", "enum": [ "md5", "sha", "sha256", "sha512" ] }, "authKey": { "type": "string", "maxLength": 128 }, "privProtocol": { "type": "string", "enum": [ "des", "aes", "aes256" ] }, "privKey": { "type": "string", "maxLength": 128 } }, "required": [ "version", "user" ] } ] } }, "required": [ "name", "host" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/switches/{id}": { "patch": { "tags": [ "network" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "host": { "type": "string", "minLength": 1, "maxLength": 255 }, "vendor": { "type": "string", "maxLength": 32 }, "siteId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "features": { "type": "array", "items": { "type": "string", "enum": [ "bw_collection", "port_admin", "poe" ] } }, "meta": { "type": "object", "additionalProperties": {} }, "credentials": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "string", "enum": [ "2c" ] }, "community": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "version", "community" ] }, { "type": "object", "properties": { "version": { "type": "string", "enum": [ "3" ] }, "user": { "type": "string", "minLength": 1, "maxLength": 64 }, "authProtocol": { "type": "string", "enum": [ "md5", "sha", "sha256", "sha512" ] }, "authKey": { "type": "string", "maxLength": 128 }, "privProtocol": { "type": "string", "enum": [ "des", "aes", "aes256" ] }, "privKey": { "type": "string", "maxLength": 128 } }, "required": [ "version", "user" ] } ] } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "network" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "get": { "tags": [ "network" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/switches/{id}/sync-ports": { "post": { "tags": [ "network" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/switches/{id}/ports": { "get": { "tags": [ "network" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/switch-ports/{id}": { "put": { "summary": "Map a switch port to a server and set its connection details", "tags": [ "network" ], "description": "`serverId: null` unmaps the port. `label` is an optional name for the connection; `poePortId` the port in POWER-ETHERNET-MIB terms (`.`, e.g. `1.12`), `poeStatusMethod` / `poeControlMethod` `snmp` read / switch PoE over SNMP (a server with power management \"PoE\" is switched there). Fields left out stay unchanged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serverId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "label": { "type": "string", "maxLength": 100 }, "poePortId": { "nullable": true, "type": "string", "pattern": "^\\d{1,5}\\.\\d{1,5}$" }, "poeStatusMethod": { "type": "string", "enum": [ "none", "snmp" ] }, "poeControlMethod": { "type": "string", "enum": [ "none", "snmp" ] } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/switch-ports/{id}/poe/status": { "post": { "summary": "Read the PoE state of a switch port", "tags": [ "network" ], "description": "Reads pethPsePortAdminEnable and pethPsePortDetectionStatus (POWER-ETHERNET-MIB) over SNMP, read-only, and stores the result on the port.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/switch-ports/{id}/admin": { "post": { "tags": [ "network" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "up": { "type": "boolean" }, "confirm": { "type": "string" } }, "required": [ "up" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/pdus": { "get": { "summary": "List PDUs", "tags": [ "network" ], "description": "Every PDU with datacenter, rack, newest totals (watts, amps, volts), outlet counts and the last poll result. Admin only.", "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Add a PDU", "tags": [ "network" ], "description": "APC (PowerNet-MIB), Raritan (PDU2-MIB) or the simulator. SNMP v2c or v3 credentials are stored encrypted and never returned. The poller reads it every 5 minutes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "host": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$" }, "vendor": { "type": "string", "enum": [ "apc", "raritan", "simulator" ] }, "siteId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "rackId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "description": { "type": "string", "maxLength": 500 }, "credentials": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "string", "enum": [ "2c" ] }, "community": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "version", "community" ] }, { "type": "object", "properties": { "version": { "type": "string", "enum": [ "3" ] }, "user": { "type": "string", "minLength": 1, "maxLength": 64 }, "authProtocol": { "type": "string", "enum": [ "md5", "sha", "sha256", "sha512" ] }, "authKey": { "type": "string", "minLength": 8, "maxLength": 128 }, "privProtocol": { "type": "string", "enum": [ "des", "aes", "aes256" ] }, "privKey": { "type": "string", "minLength": 8, "maxLength": 128 } }, "required": [ "version", "user" ] } ] } }, "required": [ "name", "host", "vendor" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/pdus/{id}": { "get": { "summary": "Get a PDU", "tags": [ "network" ], "description": "With datacenter, rack and the inlets / phases of the last reading.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "summary": "Update a PDU", "tags": [ "network" ], "description": "New `credentials` replace the stored ones.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "host": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$" }, "vendor": { "type": "string", "enum": [ "apc", "raritan", "simulator" ] }, "siteId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "rackId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "description": { "type": "string", "maxLength": 500 }, "credentials": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "string", "enum": [ "2c" ] }, "community": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "version", "community" ] }, { "type": "object", "properties": { "version": { "type": "string", "enum": [ "3" ] }, "user": { "type": "string", "minLength": 1, "maxLength": 64 }, "authProtocol": { "type": "string", "enum": [ "md5", "sha", "sha256", "sha512" ] }, "authKey": { "type": "string", "minLength": 8, "maxLength": 128 }, "privProtocol": { "type": "string", "enum": [ "des", "aes", "aes256" ] }, "privKey": { "type": "string", "minLength": 8, "maxLength": 128 } }, "required": [ "version", "user" ] } ] } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "summary": "Delete a PDU", "tags": [ "network" ], "description": "Removes the PDU, its outlets (with their server mappings) and its power history.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/pdus/{id}/refresh": { "post": { "summary": "Read a PDU now", "tags": [ "network" ], "description": "Read-only SNMP query (also the connection test): totals, inlets and outlets are stored right away. 502 with the SNMP error when the PDU does not answer.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/pdus/{id}/outlets": { "get": { "summary": "Outlets of a PDU", "tags": [ "network" ], "description": "Number, name, state, newest watts / amps (metered PDUs) and the server each outlet feeds.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/pdus/{id}/graphs/power": { "get": { "summary": "Power history of a PDU", "tags": [ "monitoring" ], "description": "5-minute totals of the whole PDU (`[time, watts, amps]`) and the energy in kWh for the range (default: the last 24 hours).", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/pdu-outlets/{id}": { "put": { "summary": "Map an outlet to a server", "tags": [ "network" ], "description": "`serverId: null` unmaps it. A server may have several outlets (redundant power supplies).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serverId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "name": { "type": "string", "maxLength": 100 } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/pdu-outlets/{id}/power": { "post": { "summary": "Switch an outlet on, off or power-cycle it", "tags": [ "power" ], "description": "Cuts or restores power at the PDU (a hard power cut for the server). Only for outlets mapped to a server; `confirm` must be the hostname of that server. Runs as a job of type `outlet_power` (dry-run unless the panel is in live mode); servers in maintenance follow the same rules as BMC power actions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "on", "off", "cycle" ] }, "confirm": { "type": "string", "maxLength": 255 } }, "required": [ "action" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/graphs/power": { "get": { "summary": "Power draw of a server", "tags": [ "monitoring" ], "description": "From the PDU outlets mapped to the server (sum of the metered outlets), otherwise from the BMC power sensor; the server's power usage measurement setting can fix the source or switch it off. `source` is `pdu`, `bmc` or null; `points` are `[time, watts]`, `kwh` the energy in the range (default: the last 24 hours), `outlets` the mapped outlets with state.", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/datacenters": { "get": { "tags": [ "racks" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/sites/{id}": { "patch": { "tags": [ "network" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "hostname": { "nullable": true, "type": "string", "maxLength": 255 }, "description": { "nullable": true, "type": "string", "maxLength": 500 }, "address": { "type": "string", "maxLength": 500 } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "summary": "Delete a site", "tags": [ "network" ], "description": "Only an empty site: no servers, racks, subnets, switches or PDUs may still belong to it (409 lists what is left), and its agent must be removed first. Admins; audited as `site.delete`.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/racks": { "get": { "tags": [ "racks" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "query", "name": "siteId", "required": false } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "racks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "location": { "default": "", "type": "string", "maxLength": 200 }, "description": { "default": "", "type": "string", "maxLength": 1000 }, "heightU": { "default": 42, "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "siteId", "name" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/racks/{id}": { "get": { "tags": [ "racks" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "tags": [ "racks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "location": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "heightU": { "type": "integer", "minimum": 1, "maximum": 60 } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "racks" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/firmware/catalog": { "get": { "tags": [ "firmware" ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "firmware" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "component": { "type": "string", "enum": [ "bios", "bmc" ] }, "match": { "type": "string", "minLength": 2, "maxLength": 100 }, "latestVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "releaseDate": { "nullable": true, "type": "string", "maxLength": 40 }, "url": { "default": "", "type": "string", "maxLength": 1000 }, "imageUrl": { "default": "", "type": "string", "maxLength": 1000 }, "notes": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "component", "match", "latestVersion" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/firmware/catalog/{id}": { "patch": { "tags": [ "firmware" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "component": { "type": "string", "enum": [ "bios", "bmc" ] }, "match": { "type": "string", "minLength": 2, "maxLength": 100 }, "latestVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "releaseDate": { "nullable": true, "type": "string", "maxLength": 40 }, "url": { "type": "string", "maxLength": 1000 }, "imageUrl": { "type": "string", "maxLength": 1000 }, "notes": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "firmware" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/firmware/overview": { "get": { "tags": [ "firmware" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/firmware/refresh": { "post": { "tags": [ "firmware" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serverIds": { "maxItems": 1000, "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } } } } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/firmware/history": { "get": { "summary": "Firmware version changes and update jobs of all servers", "tags": [ "firmware" ], "parameters": [ { "schema": { "default": 200, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/firmware/catalog/{id}/rollout": { "post": { "summary": "Update all outdated servers of a catalogue entry (one job per server)", "tags": [ "firmware" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serverIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "confirm": { "type": "string", "maxLength": 100 } }, "required": [ "confirm" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/firmware/update": { "post": { "tags": [ "firmware" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "component": { "type": "string", "enum": [ "bios", "bmc" ] }, "imageUrl": { "type": "string", "maxLength": 1000, "pattern": "^https?:\\/\\/" }, "version": { "type": "string", "maxLength": 100 }, "force": { "default": false, "type": "boolean" }, "confirm": { "type": "string", "maxLength": 253 } }, "required": [ "component" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/firmware": { "get": { "tags": [ "firmware" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/inventory": { "get": { "tags": [ "inventory" ], "parameters": [ { "schema": { "type": "string", "enum": [ "cpu", "memory", "disk", "mainboard", "nic", "gpu", "psu", "other" ] }, "in": "query", "name": "component", "required": false }, { "schema": { "type": "string", "enum": [ "installed", "spare", "defective", "rma", "retired", "stock" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "anyOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, { "type": "string", "enum": [ "none" ] } ] }, "in": "query", "name": "siteId", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "search", "required": false }, { "schema": { "default": 1, "type": "integer", "minimum": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "perPage", "required": false } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "inventory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "component": { "type": "string", "enum": [ "cpu", "memory", "disk", "mainboard", "nic", "gpu", "psu", "other" ] }, "model": { "default": "", "type": "string", "maxLength": 200 }, "value": { "default": "", "type": "string", "maxLength": 100 }, "unit": { "default": "", "type": "string", "maxLength": 20 }, "serial": { "nullable": true, "type": "string", "maxLength": 100 }, "status": { "default": "spare", "type": "string", "enum": [ "installed", "spare", "defective", "rma", "retired" ] }, "serverId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "siteId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "notes": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "component" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/inventory/{id}": { "patch": { "tags": [ "inventory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "component": { "type": "string", "enum": [ "cpu", "memory", "disk", "mainboard", "nic", "gpu", "psu", "other" ] }, "model": { "type": "string", "maxLength": 200 }, "value": { "type": "string", "maxLength": 100 }, "unit": { "type": "string", "maxLength": 20 }, "serial": { "nullable": true, "type": "string", "maxLength": 100 }, "status": { "type": "string", "enum": [ "installed", "spare", "defective", "rma", "retired" ] }, "serverId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "siteId": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "notes": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "inventory" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/inventory/stock": { "get": { "tags": [ "inventory" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "query", "name": "serverId", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/inventory/coverage": { "get": { "summary": "Which servers have hardware data and where it came from", "tags": [ "inventory" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/inventory/bmc-read": { "post": { "summary": "Read the hardware of several servers from their BMCs (background, read-only)", "tags": [ "inventory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serverIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } } }, "required": [ "serverIds" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/license": { "get": { "tags": [ "license" ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "license" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/license/activate": { "post": { "tags": [ "license" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 10, "maxLength": 64 } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/license/community": { "post": { "tags": [ "license" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/license/check": { "post": { "tags": [ "license" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/os-profiles": { "get": { "tags": [ "catalog" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "kind", "required": false }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "all", "required": false } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "catalog" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "default": "install", "type": "string", "enum": [ "install", "rescue", "hardware_collect", "disk_wipe", "password_reset", "tool" ] }, "family": { "type": "string", "enum": [ "debian", "ubuntu", "rhel", "proxmox", "windows", "live" ] }, "method": { "type": "string", "enum": [ "preseed", "autoinstall", "kickstart", "proxmox", "windows", "live" ] }, "version": { "default": "", "type": "string", "maxLength": 64 }, "arch": { "default": "amd64", "type": "string", "maxLength": 16 }, "config": { "default": {}, "type": "object", "additionalProperties": {} }, "allowSshKeys": { "default": true, "type": "boolean" }, "allowHostname": { "default": true, "type": "boolean" }, "setRootPassword": { "default": true, "type": "boolean" }, "tags": { "default": [], "type": "array", "items": { "type": "string", "maxLength": 64 } }, "enabled": { "default": true, "type": "boolean" }, "sortOrder": { "default": 100, "type": "integer" } }, "required": [ "name", "family", "method" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/os-profiles/{id}": { "patch": { "tags": [ "catalog" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "type": "string", "enum": [ "install", "rescue", "hardware_collect", "disk_wipe", "password_reset", "tool" ] }, "family": { "type": "string", "enum": [ "debian", "ubuntu", "rhel", "proxmox", "windows", "live" ] }, "method": { "type": "string", "enum": [ "preseed", "autoinstall", "kickstart", "proxmox", "windows", "live" ] }, "version": { "type": "string", "maxLength": 64 }, "arch": { "type": "string", "maxLength": 16 }, "config": { "type": "object", "additionalProperties": {} }, "allowSshKeys": { "type": "boolean" }, "allowHostname": { "type": "boolean" }, "setRootPassword": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "enabled": { "type": "boolean" }, "sortOrder": { "type": "integer" } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "catalog" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/disk-layouts": { "get": { "tags": [ "catalog" ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "catalog" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "strategy": { "type": "string", "enum": [ "auto", "largest", "smallest", "raid0", "raid1", "raid5", "raid10", "custom" ] }, "minDisks": { "default": 1, "type": "integer", "minimum": 1, "maximum": 64 }, "spare": { "default": false, "type": "boolean" }, "custom": { "nullable": true, "type": "string", "maxLength": 20000 }, "enabled": { "default": true, "type": "boolean" } }, "required": [ "name", "strategy" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/disk-layouts/{id}": { "patch": { "tags": [ "catalog" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "strategy": { "type": "string", "enum": [ "auto", "largest", "smallest", "raid0", "raid1", "raid5", "raid10", "custom" ] }, "minDisks": { "type": "integer", "minimum": 1, "maximum": 64 }, "spare": { "type": "boolean" }, "custom": { "nullable": true, "type": "string", "maxLength": 20000 }, "enabled": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "catalog" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/scripts": { "get": { "tags": [ "catalog" ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "catalog" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "content": { "type": "string", "minLength": 1, "maxLength": 200000 }, "enabled": { "default": true, "type": "boolean" } }, "required": [ "name", "content" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/scripts/{id}": { "patch": { "tags": [ "catalog" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "content": { "type": "string", "minLength": 1, "maxLength": 200000 }, "enabled": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "catalog" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/custom-isos": { "get": { "tags": [ "catalog" ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "catalog" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "source": { "type": "string", "enum": [ "url", "file" ] }, "url": { "type": "string", "maxLength": 2000, "format": "uri" }, "file": { "type": "string", "maxLength": 130 }, "description": { "default": "", "type": "string", "maxLength": 500 } }, "required": [ "name", "source" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/custom-isos/files": { "get": { "tags": [ "catalog" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/custom-isos/{id}/retry": { "post": { "tags": [ "catalog" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/custom-isos/{id}": { "delete": { "tags": [ "catalog" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/agent": { "get": { "tags": [ "network" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/sites/{id}/agent/install-token": { "post": { "tags": [ "network" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/sites/{id}/agent/update": { "post": { "tags": [ "network" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/sites/{id}/agent/targets": { "get": { "tags": [ "network" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/sites/{id}/agent": { "delete": { "summary": "Remove the site agent", "tags": [ "network" ], "description": "Revokes the agent token, so the agent on that host can no longer report or forward (its heartbeats get 401), and clears the reported state. The site and its servers stay; servers there are reached directly until an agent is installed again. Stop the agent on its host afterwards (`systemctl disable --now trixos-agent wg-quick@wg0`). Admins; audited as `agent.remove`.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/sites/{id}/agent/ssh/hostkey": { "post": { "summary": "Host key of a future agent host (SSH install, step 1)", "tags": [ "network" ], "description": "Connects to `host:port` only far enough to read its SSH host key (no login, nothing is sent) and returns its type and OpenSSH SHA256 fingerprint, plus the key confirmed for this site before (`known`) and whether it matches. Show the fingerprint to the admin to compare with `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` on the host before installing. Admins.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^[A-Za-z0-9._:[\\]-]+$" }, "port": { "default": 22, "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "host" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/sites/{id}/agent/ssh/install": { "post": { "summary": "Install (or reinstall) the site agent over SSH (step 2)", "tags": [ "network" ], "description": "Starts an `agent_install` job: the worker logs in to the host with the given user and password or private key (only if its host key is exactly `hostKey`, the fingerprint confirmed in step 1), runs the agent installer with a fresh one-time install token as root (or with sudo), and waits for the agent to register and report. The credentials are kept encrypted in the job only until it ends and are never logged or returned; a host key that differs from the one confirmed for this site before needs `trustNewKey: true`. Admins; audited as `agent.ssh_install` (without credentials). Follow the job with GET /jobs/{id}.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^[A-Za-z0-9._:[\\]-]+$" }, "port": { "default": 22, "type": "integer", "minimum": 1, "maximum": 65535 }, "username": { "type": "string", "pattern": "^[a-z_][a-z0-9_.-]{0,31}$" }, "password": { "type": "string", "minLength": 1, "maxLength": 1024 }, "privateKey": { "type": "string", "maxLength": 16384, "pattern": "-----BEGIN [A-Z ]*PRIVATE KEY-----" }, "passphrase": { "type": "string", "maxLength": 1024 }, "hostKey": { "type": "string", "pattern": "^SHA256:[A-Za-z0-9+/]{43}$" }, "trustNewKey": { "default": false, "type": "boolean" } }, "required": [ "host", "username", "hostKey" ] } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/dashboard": { "get": { "tags": [ "system" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/audit": { "get": { "tags": [ "audit" ], "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "userId", "required": false }, { "schema": { "type": "string", "maxLength": 32 }, "in": "query", "name": "targetType", "required": false }, { "schema": { "type": "string", "maxLength": 64 }, "in": "query", "name": "targetId", "required": false }, { "schema": { "type": "string", "enum": [ "web", "api", "compat", "system", "internal" ] }, "in": "query", "name": "source", "required": false }, { "schema": { "type": "string", "maxLength": 64 }, "in": "query", "name": "action", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false }, { "schema": { "default": 200, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer" }, "in": "query", "name": "beforeId", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/settings": { "get": { "tags": [ "system" ], "responses": { "200": { "description": "Default Response" } } }, "put": { "tags": [ "system" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/system/status": { "get": { "tags": [ "system" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/webhooks": { "get": { "tags": [ "system" ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "system" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "format": "uri" }, "secret": { "type": "string", "minLength": 16, "maxLength": 200 }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "enabled": { "default": true, "type": "boolean" } }, "required": [ "url", "events" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/webhooks/{id}": { "delete": { "tags": [ "system" ], "parameters": [ { "schema": { "type": "integer" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/settings/labels": { "get": { "summary": "QR label settings", "tags": [ "system" ], "description": "Logo (Trivox, TrixOS or a custom PNG), its position, height and width on the label, and the text sizes. The mark in the middle of the QR code is fixed. Admins.", "responses": { "200": { "description": "Default Response" } } }, "put": { "summary": "Update the QR label settings", "tags": [ "system" ], "description": "`customLogo` is a PNG data URL (at most 256 KB, 4000 × 4000 px; the panel converts SVG, JPEG and WebP to PNG in the browser); `null` removes it. `logo: \"custom\"` needs a custom logo. Admins; audited as `settings.labels`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "logo": { "type": "string", "enum": [ "trivox", "trixos", "custom" ] }, "position": { "type": "string", "enum": [ "below", "above", "right", "none" ] }, "size": { "type": "integer", "minimum": 10, "maximum": 80 }, "logoWidth": { "nullable": true, "type": "integer", "minimum": 10, "maximum": 100 }, "keepRatio": { "type": "boolean" }, "hostnameScale": { "type": "integer", "minimum": 50, "maximum": 200 }, "textScale": { "type": "integer", "minimum": 50, "maximum": 200 }, "customLogo": { "nullable": true, "type": "string", "maxLength": 349558 } } } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/system/health": { "get": { "summary": "Health of the control server and the site agents", "tags": [ "system" ], "description": "For the dashboard (admins). Control server: status with reasons, CPU, load, memory and disk of the panel host, uptime, the services (API, worker, poller, PXE/asset service) from their heartbeats (a poller task over its watchdog budget is a warning with the reason), Postgres (latency, database size), Redis (latency, memory), job queue, license and version. `watchdog`: what the watchdog stopped or warned about in the last 24 hours (jobs, poller tasks, console sessions, API loops), newest first. Site agents: online state, version (update available / pending), WireGuard handshake, PXE state, CPU, load, memory and disk (agent ≥ 1.3.0). `history` holds one point per minute for the last 24 hours: `[unix seconds, CPU %, memory %, disk %, load]`. Levels: `ok`, `warn`, `error` (`none` for a site without an agent).", "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/system/watchdog": { "get": { "summary": "Watchdog limits and its actions of the last 24 hours", "tags": [ "system" ], "description": "Admins. `limits`: the limit per job type and per step in minutes (defaults, overridden by `TRIXOS_WATCHDOG_LIMITS` and the setting `watchdog`), poller task budgets, the queue / dead-worker / resume limits. `events`: what the watchdog stopped (jobs, console sessions) or warned about (poller tasks, API loops over their budget) in the last `hours` (default 24, max 72), newest first, with the reason.", "parameters": [ { "schema": { "default": 24, "type": "integer", "minimum": 1, "maximum": 72 }, "in": "query", "name": "hours", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/config": { "get": { "summary": "Configuration of a server", "tags": [ "servers" ], "description": "Everything the Configuration tab shows. Admins get all sections (connections, IPMI device without passwords, DHCP / PXE, switch ports with PoE, PDU outlets, choices). Admins also get `bmc.webConsoleEnabled` (the BMC web interface is offered at all). Owners get the main details, which consoles the server offers (`bmc.webConsole`: the BMC web interface with an account of their own) and whether they may read the client BMC account (`bmc.credentialsAvailable`).", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/connections": { "put": { "summary": "Assigned connections of a server", "tags": [ "servers" ], "description": "Which connection does what: `powerManagement` `bmc` (IPMI / Redfish), `pdu` (all mapped PDU outlets switch together), `poe` (the PoE switch port with control method SNMP) or `none` (no power actions, no PXE jobs); `reinstallProvider` `pxe` or `none` (no reinstall, rescue, inventory scan, wipe); `remoteConsole` `bmc` or `none` (no KVM / serial console); `powerUsageSource` for the power graph (`auto` = PDU outlets when metered, else the BMC sensor). Admins only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "powerManagement": { "type": "string", "enum": [ "bmc", "pdu", "poe", "none" ] }, "reinstallProvider": { "type": "string", "enum": [ "pxe", "none" ] }, "remoteConsole": { "type": "string", "enum": [ "bmc", "none" ] }, "powerUsageSource": { "type": "string", "enum": [ "auto", "pdu", "bmc", "none" ] } } } } } }, "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/connections/{kind}": { "delete": { "summary": "Remove a connection from a server", "tags": [ "servers" ], "description": "The DELETE button of a connection card (TenantOS style). `dhcp`: clears the PXE MAC (no DHCP answers for this server); `pxe`: reinstallation provider none, boot mode auto and the default iPXE files; `switch`: unmaps every switch port of the server; `pdu`: unmaps every PDU outlet of the server; `power-usage`: no power graph. Removing the PDU or switch connection that powers the server moves power management back to the BMC (or none without one). The main details and the IPMI device cannot be removed here. Admins only; refused while a PXE job of the server runs (dhcp, pxe).", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "enum": [ "dhcp", "pxe", "switch", "pdu", "power-usage" ] }, "in": "path", "name": "kind", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/servers/{id}/bmc/credentials": { "get": { "summary": "BMC access for the customer", "tags": [ "servers" ], "description": "Address and the client BMC account (username and password) of a server, when an admin entered a client account and allowed showing it (\"Show IPMI credentials\"). Owners and admins; the admin account of the BMC is never returned. Every read is written to the audit log.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/console/{token}": { "get": { "summary": "Console session", "tags": [ "console" ], "description": "State of a console session for the console page: `pending` (token not used yet), `active`, `ended` (with `endReason`: closed, user, console, error, restart, watchdog = open longer than 8 h) or `expired`; the server and its last known power state; whether the page may show the BMC login (`loginAvailable`). Authenticated by the console token in the path, from the IP it was issued for.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "in": "path", "name": "token", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/console/{token}/login": { "post": { "summary": "BMC login of a console session", "tags": [ "console" ], "description": "The BMC account the viewer logged in with, for when the automatic login fails: the temporary BMC user of the session, the client account, or (admins only) the stored account. Only while the session is active and when the IPMI device allows it (Configuration → IPMI device → Login details on the console page). Audited.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "in": "path", "name": "token", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/console/{token}/end": { "post": { "summary": "End a console session", "tags": [ "console" ], "description": "Ends the session now: the websocket closes, the viewer stops and a temporary BMC user is deleted. The console page calls it for \"End session\" and when its window closes (sendBeacon). Idempotent.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "in": "path", "name": "token", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/system/update": { "get": { "summary": "Update status", "tags": [ "system" ], "description": "This version, the newest release (with its changelog entry and whether its signed release record verifies), whether the host updater is installed, and the state and log of the last update. `refresh=1` checks the release server again (otherwise cached for an hour).", "parameters": [ { "schema": { "type": "string", "enum": [ "0", "1" ] }, "in": "query", "name": "refresh", "required": false } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Update TrixOS", "tags": [ "system" ], "description": "Asks the host updater to install `version`, which must be the newest release, newer than this one and signed with a trusted release key. The updater backs up the database, verifies the release again, installs it, checks health and rolls back if the new version does not come up. Follow it with GET /system/update.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "pattern": "^\\d{1,4}\\.\\d{1,4}\\.\\d{1,4}$" } }, "required": [ "version" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/servers": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/getByIp/{ip}": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "ip", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "put": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/power/{action}": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "action", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "action", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/bmc/executeCommand": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/console/start": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/provisioning/startReinstallation": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/provisioning/stopReinstallation": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/provisioning/getProfiles": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/ipassignments": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/ipassignments/getAssignableIpsOfSubnet": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/ipassignments/getAssignableSubnets": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/ipassignments/{assignmentId}": { "put": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "assignmentId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/ipassignments/ip": { "delete": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/ip/comment": { "post": { "responses": { "200": { "description": "Default Response" } } } }, "/api/ip/unreserve": { "post": { "responses": { "200": { "description": "Default Response" } } } }, "/api/ip/reserve": { "post": { "responses": { "200": { "description": "Default Response" } } } }, "/api/subnets": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/api/subnets/{id}": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/subnets/{id}/withDetails": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/servers/{id}/connections": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/pxe/profiles": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/api/pxe/disklayouts": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/api/pxe/scripts": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/api/users": { "get": { "responses": { "200": { "description": "Default Response" } } }, "post": { "responses": { "200": { "description": "Default Response" } } } }, "/api/users/{id}": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/users/{id}/tokens": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/users/{id}/sshkeys": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/users/{id}/sshkeys/{keyId}": { "delete": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "keyId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/pxe/boot.ipxe": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/pxe/boot": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/pxe/jobs/{jobId}/{token}/{file}": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "jobId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "token", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "file", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/pxe/assets/{*}": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "*", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/pxe/isos/{file}": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "file", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/internal/jobs/{id}/progress": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/internal/jobs/{id}/log": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/internal/jobs/{id}/smart": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/internal/jobs/{id}/tasks": { "get": { "summary": "Rescue system task poll (job token)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/internal/jobs/{id}/hardware": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/internal/agent/pxe": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "applied": { "default": [], "maxItems": 256, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "httpBase": { "default": null, "nullable": true, "type": "string", "pattern": "^http:\\/\\/\\d{1,3}(\\.\\d{1,3}){3}:\\d{2,5}$" }, "problem": { "default": null, "nullable": true, "type": "string", "maxLength": 500 }, "events": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "at": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "kind": { "type": "string", "enum": [ "discover", "offer", "request", "ack", "nak", "tftp", "tftp_error" ] }, "mac": { "type": "string", "pattern": "^[0-9a-f]{2}(:[0-9a-f]{2}){5}$" }, "ip": { "nullable": true, "type": "string", "maxLength": 45 }, "vendor": { "nullable": true, "type": "string", "maxLength": 100 }, "user": { "nullable": true, "type": "string", "maxLength": 100 }, "ignored": { "type": "boolean" }, "detail": { "nullable": true, "type": "string", "maxLength": 300 } }, "required": [ "at", "kind", "mac" ] } } } } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/agent/install.sh": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/agent/trixos-agent.py": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/agent/agent-firewall.sh": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/api/internal/agent/register": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installToken": { "type": "string", "pattern": "^\\d+\\.[0-9a-f]{40}$" }, "hostname": { "default": "", "type": "string", "maxLength": 253 }, "wgPublicKey": { "default": "", "type": "string", "maxLength": 64 } }, "required": [ "installToken" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/internal/agent/heartbeat": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "maxLength": 32 }, "hostname": { "default": "", "type": "string", "maxLength": 253 }, "uptimeS": { "default": 0, "type": "number", "minimum": 0 }, "os": { "default": "", "type": "string", "maxLength": 200 }, "wg": { "default": {}, "type": "object", "properties": { "handshakeAgeS": { "nullable": true, "type": "number" }, "endpoint": { "nullable": true, "type": "string", "maxLength": 100 }, "publicKey": { "nullable": true, "type": "string", "maxLength": 64 } } }, "allowed": { "default": [], "maxItems": 4096, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "metrics": { "type": "object", "properties": { "cpuPct": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "cpus": { "type": "integer", "minimum": 1, "maximum": 4096 }, "load": { "type": "array", "items": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "number", "minimum": 0 }, { "type": "number", "minimum": 0 } ] }, "minItems": 3, "maxItems": 3 }, "memTotal": { "type": "number", "minimum": 0 }, "memAvailable": { "type": "number", "minimum": 0 }, "diskPath": { "default": "/", "type": "string", "maxLength": 200 }, "diskTotal": { "type": "number", "minimum": 0 }, "diskUsed": { "type": "number", "minimum": 0 }, "diskAvail": { "type": "number", "minimum": 0 } }, "required": [ "cpuPct", "cpus", "load", "memTotal", "memAvailable", "diskTotal", "diskUsed", "diskAvail" ] } }, "required": [ "version" ] } } } }, "responses": { "200": { "description": "Default Response" } } } } }, "security": [ { "bearer": [] } ] }