Kerrigan REST API

Local admin access only

Use this REST API only for local control when the controller has direct network access to the Kerrigan admin interface. In the normal cloud-control deployment, controllers do not have access to this REST API. Use Kerrigan's cloud-control interfaces instead.

The generated reference below documents Kerrigan's local REST API from the committed OpenAPI schema. Requests operate on the Kerrigan appliance reached by the client and can change fleet, device, user, image, and workflow state.

openapi.json is generated from the FastAPI application source and published with this documentation as openapi.json.

Regenerate it with:

PYTHONPATH=src python scripts/export_openapi.py

Check whether the committed schema is current:

PYTHONPATH=src python scripts/export_openapi.py --check

When you have direct access to a local Kerrigan installation, its Fleet Manager also exposes interactive Swagger UI at /docs and the same OpenAPI schema at /openapi.json.

Utilization history

Kerrigan stores the latest controller and DevKit utilization sample for each UTC minute and retains 24 hours of history. The Dashboard requests five-minute averages for time-series views, including CPU, memory, filesystem, uplink, and downlink utilization when those measurements are available.

• GET /v1/kerrigan/metrics/history returns controller history.
• GET /v1/targets/{target_id}/metrics/history returns history for one DevKit.

Both endpoints accept hours from 1 through 24 and bucket_minutes from 1 through 60. Empty buckets are returned with samples: 0 so clients can show gaps instead of connecting measurements across missing data.

Maintenance controls

Use local REST controls for persistent appliance, pool, or device maintenance:

Endpoint	Purpose
GET /v1/maintenance/{scope}/{scope_id}	Read scope intent, inherited scopes, and effective maintenance state for affected devices.
PUT /v1/maintenance/{scope}/{scope_id}	Save intent using enabled and an optional reason (up to 500 characters). Requires an administrator session.

Use global/all, pool/{pool_id}, or device/{target_id}. Pool IDs are local to this Kerrigan instance. A successful PUT returns 202 Accepted; it does not mean runner operations have finished. Poll the GET response until affected devices report phase: "active" for entry, or phase: "normal" and blocked: false for exit. Clearing a device scope does not override inherited appliance/pool intent.

See Maintenance for dashboard controls, a REST request example, and the complete lifecycle. Cloud callers use the MQTT maintenance operation, which accepts explicit device IDs rather than local scope selectors.