Network & sites

Sites (datacenters), switches, switch ports and site agents.

30 endpoints

Switch ports of a server

GET/api/v1/servers/{id}/switch-ports

Path parameters

id integer> 0

Example

curl "https://panel.example.com/api/v1/servers/42/switch-ports" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

List sites (datacenters)

GET/api/v1/sites

Example

curl "https://panel.example.com/api/v1/sites" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Add a site

POST/api/v1/sites

Admin only

Request body

namestringrequired
min. 1 chars, max. 100 chars
hostnamestring | null
max. 255 chars
descriptionstring | null
max. 500 chars
addressstring
max. 500 chars

Example

curl -X POST "https://panel.example.com/api/v1/sites" \
  -H "Authorization: Bearer $TRIXOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"example"}'

List switches

GET/api/v1/switches

Admin only

Example

curl "https://panel.example.com/api/v1/switches" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Add a switch

POST/api/v1/switches

Admin only

SNMP v2c or v3 credentials are stored encrypted.

Request body

namestringrequired
min. 1 chars, max. 100 chars
hoststringrequired
min. 1 chars, max. 255 chars
vendorstring
max. 32 chars, default "generic"
siteIdinteger | null
> 0
featuresstring[]
default ["bw_collection"]
metaobject (map)
default {}
credentialsobject

Example

curl -X POST "https://panel.example.com/api/v1/switches" \
  -H "Authorization: Bearer $TRIXOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"example","host":"host"}'

Get a switch

GET/api/v1/switches/{id}

Admin only

Path parameters

id integer> 0

Example

curl "https://panel.example.com/api/v1/switches/42" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Update a switch

PATCH/api/v1/switches/{id}

Admin only

Path parameters

id integer> 0

Request body

namestring
min. 1 chars, max. 100 chars
hoststring
min. 1 chars, max. 255 chars
vendorstring
max. 32 chars
siteIdinteger | null
> 0
featuresstring[]
metaobject (map)
credentialsobject

Example

curl -X PATCH "https://panel.example.com/api/v1/switches/42" \
  -H "Authorization: Bearer $TRIXOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"example","host":"host","vendor":"vendor"}'

Delete a switch

DELETE/api/v1/switches/{id}

Admin only

Path parameters

id integer> 0

Example

curl -X DELETE "https://panel.example.com/api/v1/switches/42" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Read the port list over SNMP

POST/api/v1/switches/{id}/sync-ports

Admin only

Read-only SNMP walk of IF-MIB to refresh the port list.

Path parameters

id integer> 0

Example

curl -X POST "https://panel.example.com/api/v1/switches/42/sync-ports" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Ports of a switch

GET/api/v1/switches/{id}/ports

Admin only

With mapping and the newest 5-minute rate per port.

Path parameters

id integer> 0

Example

curl "https://panel.example.com/api/v1/switches/42/ports" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Map a switch port to a server and set its connection details

PUT/api/v1/switch-ports/{id}

Admin only

serverId: null unmaps the port. label is an optional name for the connection; poePortId the port in POWER-ETHERNET-MIB terms (<group>.<port>, 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.

Path parameters

id integer> 0

Request body

serverIdinteger | null
> 0
labelstring
max. 100 chars
poePortIdstring | null
pattern ^\d{1,5}\.\d{1,5}$
poeStatusMethodstring
one of none, snmp
poeControlMethodstring
one of none, snmp

Example

curl -X PUT "https://panel.example.com/api/v1/switch-ports/42" \
  -H "Authorization: Bearer $TRIXOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":42}'

Read the PoE state of a switch port

POST/api/v1/switch-ports/{id}/poe/status

Admin only

Reads pethPsePortAdminEnable and pethPsePortDetectionStatus (POWER-ETHERNET-MIB) over SNMP, read-only, and stores the result on the port.

Path parameters

id integer> 0

Example

curl -X POST "https://panel.example.com/api/v1/switch-ports/42/poe/status" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Shut down or enable a port

POST/api/v1/switch-ports/{id}/admin

Admin onlyNeeds confirm with the hostname

Needs port admin on the switch and confirm with the hostname of the mapped server.

Path parameters

id integer> 0

Request body

upbooleanrequired
confirmstring

Example

curl -X POST "https://panel.example.com/api/v1/switch-ports/42/admin" \
  -H "Authorization: Bearer $TRIXOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"up":false,"confirm":"web-01"}'

List PDUs

GET/api/v1/pdus

Admin only

Every PDU with datacenter, rack, newest totals (watts, amps, volts), outlet counts and the last poll result. Admin only.

Example

curl "https://panel.example.com/api/v1/pdus" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Add a PDU

POST/api/v1/pdus

Admin only

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.

Request body

namestringrequired
min. 1 chars, max. 100 chars
hoststringrequired
min. 1 chars, max. 255 chars, pattern ^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$
vendorstringrequired
one of apc, raritan, simulator
siteIdinteger | null
> 0
rackIdinteger | null
> 0
descriptionstring
max. 500 chars
credentialsobject

Example

curl -X POST "https://panel.example.com/api/v1/pdus" \
  -H "Authorization: Bearer $TRIXOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"example","host":"host","vendor":"apc"}'

Get a PDU

GET/api/v1/pdus/{id}

Admin only

With datacenter, rack and the inlets / phases of the last reading.

Path parameters

id integer> 0

Example

curl "https://panel.example.com/api/v1/pdus/42" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Update a PDU

PATCH/api/v1/pdus/{id}

Admin only

New credentials replace the stored ones.

Path parameters

id integer> 0

Request body

namestring
min. 1 chars, max. 100 chars
hoststring
min. 1 chars, max. 255 chars, pattern ^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$
vendorstring
one of apc, raritan, simulator
siteIdinteger | null
> 0
rackIdinteger | null
> 0
descriptionstring
max. 500 chars
credentialsobject

Example

curl -X PATCH "https://panel.example.com/api/v1/pdus/42" \
  -H "Authorization: Bearer $TRIXOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"example","host":"host","vendor":"apc"}'

Delete a PDU

DELETE/api/v1/pdus/{id}

Admin only

Removes the PDU, its outlets (with their server mappings) and its power history.

Path parameters

id integer> 0

Example

curl -X DELETE "https://panel.example.com/api/v1/pdus/42" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Read a PDU now

POST/api/v1/pdus/{id}/refresh

Admin only

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.

Path parameters

id integer> 0

Example

curl -X POST "https://panel.example.com/api/v1/pdus/42/refresh" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Outlets of a PDU

GET/api/v1/pdus/{id}/outlets

Admin only

Number, name, state, newest watts / amps (metered PDUs) and the server each outlet feeds.

Path parameters

id integer> 0

Example

curl "https://panel.example.com/api/v1/pdus/42/outlets" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Map an outlet to a server

PUT/api/v1/pdu-outlets/{id}

Admin only

serverId: null unmaps it. A server may have several outlets (redundant power supplies).

Path parameters

id integer> 0

Request body

serverIdinteger | null
> 0
namestring
max. 100 chars

Example

curl -X PUT "https://panel.example.com/api/v1/pdu-outlets/42" \
  -H "Authorization: Bearer $TRIXOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":1,"name":"example"}'

Update a site

PATCH/api/v1/sites/{id}

Admin only

Path parameters

id integer> 0

Request body

namestring
min. 1 chars, max. 100 chars
hostnamestring | null
max. 255 chars
descriptionstring | null
max. 500 chars
addressstring
max. 500 chars

Example

curl -X PATCH "https://panel.example.com/api/v1/sites/42" \
  -H "Authorization: Bearer $TRIXOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"example","hostname":"web-01","description":"Example"}'

Delete a site

DELETE/api/v1/sites/{id}

Admin only

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.

Path parameters

id integer> 0

Example

curl -X DELETE "https://panel.example.com/api/v1/sites/42" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Site agent release

GET/api/v1/agent

Admin only

Version and checksum of the agent shipped with this release.

Example

curl "https://panel.example.com/api/v1/agent" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Create an agent install command

POST/api/v1/sites/{id}/agent/install-token

Admin only

One-time token, valid for one hour, and the full install command.

Path parameters

id integer> 0

Example

curl -X POST "https://panel.example.com/api/v1/sites/42/agent/install-token" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Ask the agent to update itself

POST/api/v1/sites/{id}/agent/update

Admin only

Path parameters

id integer> 0

Example

curl -X POST "https://panel.example.com/api/v1/sites/42/agent/update" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Forwarding targets of a site

GET/api/v1/sites/{id}/agent/targets

Admin only

BMC and switch addresses the site agent lets the panel reach.

Path parameters

id integer> 0

Example

curl "https://panel.example.com/api/v1/sites/42/agent/targets" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Remove the site agent

DELETE/api/v1/sites/{id}/agent

Admin only

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.

Path parameters

id integer> 0

Example

curl -X DELETE "https://panel.example.com/api/v1/sites/42/agent" \
  -H "Authorization: Bearer $TRIXOS_TOKEN"

Host key of a future agent host (SSH install, step 1)

POST/api/v1/sites/{id}/agent/ssh/hostkey

Admin only

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.

Path parameters

id integer> 0

Request body

hoststringrequired
min. 1 chars, max. 253 chars, pattern ^[A-Za-z0-9._:[\]-]+$
portinteger
≥ 1, ≤ 65535, default 22

Example

curl -X POST "https://panel.example.com/api/v1/sites/42/agent/ssh/hostkey" \
  -H "Authorization: Bearer $TRIXOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host":"host"}'

Install (or reinstall) the site agent over SSH (step 2)

POST/api/v1/sites/{id}/agent/ssh/install

Admin only

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}.

Path parameters

id integer> 0

Request body

hoststringrequired
min. 1 chars, max. 253 chars, pattern ^[A-Za-z0-9._:[\]-]+$
portinteger
≥ 1, ≤ 65535, default 22
usernamestringrequired
pattern ^[a-z_][a-z0-9_.-]{0,31}$
passwordstring
min. 1 chars, max. 1024 chars
privateKeystring
max. 16384 chars, pattern -----BEGIN [A-Z ]*PRIVATE KEY-----
passphrasestring
max. 1024 chars
hostKeystringrequired
pattern ^SHA256:[A-Za-z0-9+/]{43}$
trustNewKeyboolean
default false

Example

curl -X POST "https://panel.example.com/api/v1/sites/42/agent/ssh/install" \
  -H "Authorization: Bearer $TRIXOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host":"host","username":"customer42","hostKey":"hostKey"}'