Skip to content
LabTether

API v2 Reference

Base URL: https://hub:8443/api/v2/

All endpoints except /openapi.json require authentication via API key (Authorization: Bearer lt_...) or session cookie.

Response Format

Success:

{
  "request_id": "req_a1b2c3d4",
  "data": { ... }
}

List with pagination:

{
  "request_id": "req_a1b2c3d4",
  "data": [ ... ],
  "meta": { "total": 42, "page": 1, "per_page": 50 }
}

Error:

{
  "request_id": "req_a1b2c3d4",
  "error": "asset_offline",
  "message": "server1 agent is not connected",
  "status": 409
}

Discovery

Method Path Scope Description
GET /whoami — Key info, scopes, accessible assets

API Keys (admin only)

Method Path Description
POST /keys Create key (returns raw_key once)
GET /keys List all keys
GET /keys/{id} Key details
PATCH /keys/{id} Update name/scopes/expiry
DELETE /keys/{id} Revoke key

Assets

Method Path Scope Description
GET /assets assets:read List assets (?status=online&platform=linux)
GET /assets/{id} assets:read Asset details + agent status
POST /assets assets:write Add manual device
PUT /assets/{id} assets:write Update asset
DELETE /assets/{id} assets:write Remove asset

Execution

Method Path Scope Description
POST /assets/{id}/exec assets:exec Run command (one-shot, default 30s timeout)
POST /exec assets:exec Multi-target fan-out (targets array or group)

Exec request:

{"command": "df -h", "timeout": 30}

Multi-target request:

{"targets": ["srv1", "srv2"], "command": "uptime", "timeout": 30}

Offline asset response (409):

{"error": "asset_offline", "message": "srv1 agent is not connected (last seen: 2026-03-17T08:30:00Z)"}

Files

Method Path Scope Description
GET /assets/{id}/files?path=/var/log files:read List directory
GET /assets/{id}/files/read?path=/etc/hostname files:read Download file
POST /assets/{id}/files/write files:write Upload file
POST /assets/{id}/files/mkdir files:write Create directory
POST /assets/{id}/files/rename files:write Rename/move
POST /assets/{id}/files/copy files:write Copy
DELETE /assets/{id}/files?path=... files:write Delete

System Info

Method Path Scope Description
GET /assets/{id}/processes processes:read List processes
POST /assets/{id}/processes/kill processes:kill Kill process
GET /assets/{id}/services services:read List services
POST /assets/{id}/services/{name}/start services:write Start service
POST /assets/{id}/services/{name}/stop services:write Stop service
POST /assets/{id}/services/{name}/restart services:write Restart service
GET /assets/{id}/network network:read Network interfaces
GET /assets/{id}/disks disks:read Disk usage
GET /assets/{id}/packages packages:read Installed packages
GET /assets/{id}/cron cron:read Cron jobs
GET /assets/{id}/users users:read System users
GET /assets/{id}/logs logs:read Query logs
GET /assets/{id}/metrics metrics:read Asset metrics

Power Management

Method Path Scope Description
POST /assets/{id}/wake assets:power Wake-on-LAN
POST /assets/{id}/reboot assets:power Reboot
POST /assets/{id}/shutdown assets:power Shutdown

Docker

Method Path Scope Description
GET /docker/hosts docker:read List Docker hosts
GET /docker/hosts/{id}/containers docker:read List containers
POST /docker/containers/{id}/start docker:write Start container
POST /docker/containers/{id}/stop docker:write Stop container
POST /docker/containers/{id}/restart docker:write Restart container
GET /docker/containers/{id}/logs docker:read Container logs
GET /docker/stacks/{id} docker:read Stack details

Connectors

Method Path Scope Description
GET /connectors connectors:read List connectors
GET /connectors/{id} connectors:read Connector details
GET /proxmox/cluster/status connectors:read Proxmox cluster health
GET /proxmox/cluster/resources connectors:read All VMs/CTs
POST /proxmox/assets/{id}/start connectors:write Start VM/CT
POST /proxmox/assets/{id}/stop connectors:write Stop VM/CT
GET /proxmox/ceph/status connectors:read Ceph health
GET /truenas/assets/{id}/pools connectors:read Storage pools
GET /truenas/assets/{id}/datasets connectors:read Datasets
GET /pbs/assets/{id}/datastores connectors:read PBS datastores
GET /portainer/assets/{id}/stacks connectors:read Portainer stacks

Groups, Alerts, Incidents

Method Path Scope Description
GET /groups groups:read List groups
POST /groups groups:write Create group
GET /alerts alerts:read Active alerts
POST /alerts/{id}/acknowledge alerts:write Acknowledge
POST /alerts/{id}/silence alerts:write Silence
GET /incidents alerts:read List incidents
POST /incidents/{id}/resolve alerts:write Resolve

Metrics

Method Path Scope Description
GET /metrics/overview metrics:read Fleet-wide summary

Webhooks

Method Path Scope Description
POST /webhooks webhooks:write Register webhook
GET /webhooks webhooks:read List webhooks
GET /webhooks/{id} webhooks:read Get webhook
PUT/PATCH /webhooks/{id} webhooks:write Update webhook
DELETE /webhooks/{id} webhooks:write Remove webhook

Webhook deliveries contain a unique id, the event type, bounded JSON data, and an RFC 3339 ts. When a secret is configured, verify the X-Labtether-Signature-256 HMAC using the timestamp header and raw request body. Delivery is a bounded, best-effort live event stream rather than a durable message queue: consumers should tolerate gaps during hub restarts or sustained backpressure and reconcile authoritative state through the API.

Scheduled Tasks

Method Path Scope Description
POST /schedules schedules:write Create scheduled task
GET /schedules schedules:read List tasks
DELETE /schedules/{id} schedules:write Remove task

Saved Actions

Method Path Scope Description
POST /actions actions:write Create action
GET /actions actions:read List actions
POST /actions/{id}/run actions:exec Execute action
Method Path Scope Description
GET /search?q=nginx search:read Search assets and groups

Other Endpoints

Method Path Scope Description
GET /hub/status hub:read Hub health
GET /hub/agents hub:read Connected agents
GET /hub/tls hub:read TLS certificate status
GET /audit/events audit:read Audit trail
GET /events/stream events:subscribe WebSocket event feed
POST /discovery/run discovery:write Trigger network discovery
GET /dependencies topology:read Infrastructure graph
POST /bulk/service-action bulk:* Bulk service control