Documentation
API docs by Redocly

Vapor API (1.0.0)

Download OpenAPI specification:

RESTful API for Vapor a web console for modern Linux stacks.

Key Features

  • System management and monitoring - Network configuration - Storage management - Virtual machine management - Container and Kubernetes support - Resumable file uploads using TUS protocol

TUS Protocol Support

This API implements the TUS Protocol v1.0.0 for resumable file uploads, specifically for:

  • ISO images for virtual machines (/virtualmachines/isos/upload/*)
  • Container images (/containers/images/upload/*)
  • Docker images (/docker/images/upload/*)

What is TUS?

TUS is an open protocol for resumable file uploads via HTTP/1.1 and HTTP/2. It allows:

  • Resume interrupted uploads: Network failures don't mean starting over
  • Upload large files reliably: Perfect for multi-GB ISO and container images
  • Monitor progress: Real-time upload progress tracking
  • Automatic retry: Built-in resilience to network issues

How to Use TUS Endpoints

1. Create Upload Session
POST /api/v1/virtualmachines/isos/upload
Headers:
  Upload-Length: 1474560000  # File size in bytes
  Upload-Metadata: filename aXNvLXVidW50dS0yMi4wNC5pc28=  # Base64 encoded metadata

Returns:

  • 201 Created with Location header containing upload URL
  • Upload session ID in response body
2. Upload File Chunks
PATCH /api/v1/virtualmachines/isos/upload/{upload_id}
Headers:
  Upload-Offset: 0  # Starting byte position
  Content-Type: application/offset+octet-stream
Body: [binary data chunk]
  • Chunk size: 1MB - 50MB recommended
  • Returns new offset after successful upload
3. Resume Interrupted Upload
HEAD /api/v1/virtualmachines/isos/upload/{upload_id}

Returns current Upload-Offset to resume from

4. Complete Upload
POST /api/v1/virtualmachines/isos/upload/{upload_id}/complete

Finalizes upload and registers the file in the system

Frontend Implementation

For frontend applications, we recommend using:

  • tus-js-client: Official JavaScript client library
  • Uppy: Modern file upload library with TUS support
  • Fine Uploader: Enterprise-grade upload solution

Example with tus-js-client:

import * as tus from 'tus-js-client';

const upload = new tus.Upload(file, {
  endpoint: '/api/v1/virtualmachines/isos/upload',
  headers: {
    'Authorization': 'Bearer ' + token
  },
  chunkSize: 10 * 1024 * 1024, // 10MB chunks
  metadata: {
    filename: file.name,
    filetype: file.type
  },
  onError: (error) => console.error('Upload failed:', error),
  onProgress: (bytesUploaded, bytesTotal) => {
    const percentage = (bytesUploaded / bytesTotal * 100).toFixed(2);
    console.log(percentage + '% uploaded');
  },
  onSuccess: () => {
    console.log('Upload complete');
    // Call complete endpoint to finalize
    fetch(`/api/v1/virtualmachines/isos/upload/${upload.url.split('/').pop()}/complete`, {
      method: 'POST',
      headers: { 'Authorization': 'Bearer ' + token }
    });
  }
});

upload.start();

Benefits for Large Files

  • Reliability: Automatic resume on network failures
  • Efficiency: Only retransmit failed chunks
  • User Experience: Show accurate progress, pause/resume capability
  • Bandwidth Optimization: Configurable chunk sizes
  • Server Resources: Reduced memory usage with streaming uploads

Licensing

Get current license status

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "state": "string",
  • "restricted": true
}

Create an installation request payload

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{ }

Import a standalone license

Authorizations:
bearerAuth
Request Body schema: application/json
required
object

Raw signed LicenseDocument JSON received from Vapor CE (no additional payload envelope)

Responses

Request samples

Content type
application/json
{ }

Import a managed allocation

Authorizations:
bearerAuth
Request Body schema: application/json
required
object

Raw signed ManagedAllocation JSON received from Cockpit Control Plane (no additional payload envelope)

Responses

Request samples

Content type
application/json
{ }

Remove the current license or managed allocation

Authorizations:
bearerAuth

Responses

Virtualization Compute

Download a VM backup artifact

Download the qcow2 backup file by backup ID

Authorizations:
bearerAuth
path Parameters
backup_id
required
string

Backup ID

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Import an existing backup file

Register an existing qcow2 backup file on disk into the backup catalog

Authorizations:
bearerAuth
Request Body schema: application/json
required
backup_id
string

Optional ID to register; if omitted the server generates one

vm_uuid
string

Optional VM UUID to associate with the backup

vm_name
required
string

VM name the backup belongs to

path
required
string

Absolute path to the existing qcow2 backup file on disk

type
string
Default: "full"
Enum: "full" "incremental" "differential"

Backup type

compression
string
Default: "none"
Enum: "none" "gzip" "bzip2" "xz" "zstd"

Compression used in the backup file

encryption
string
Default: "none"
Enum: "none" "aes256" "aes128"

Encryption used in the backup file

retention_days
integer

Retention policy in days

description
string

Optional description metadata

Responses

Request samples

Content type
application/json
{
  • "backup_id": "string",
  • "vm_uuid": "string",
  • "vm_name": "myvm",
  • "path": "/var/lib/libvirt/vapor-backups/myvm/myvm-abc123.qcow2",
  • "type": "full",
  • "compression": "none",
  • "encryption": "none",
  • "retention_days": 30,
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List all VM backups

List backups across all VMs

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List all virtual machines

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create a new virtual machine

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Name of the virtual machine

memory
required
integer >= 256

Memory size in MB

vcpus
required
integer [ 1 .. 256 ]

Number of virtual CPUs

max_memory
integer >= 0

Maximum memory limit in MB (0 = same as memory)

max_vcpus
integer [ 0 .. 256 ]

Maximum vCPU limit (0 = same as vcpus)

object

Optional CPU model and topology configuration. If omitted, Vapor uses a simple topology-only CPU element:

required
object (StorageConfig)
os_type
string

Operating system type

os_variant
string

Operating system variant

object (OSInfoEnhanced)

Detailed OS information for metadata and optimization

architecture
string
Default: "x86_64"

System architecture

machine_type
string
Default: "q35"

Machine type (q35, pc, virt, etc)

uefi
boolean
Default: false

Use UEFI boot

secure_boot
boolean
Default: false

Enable secure boot

tpm
boolean
Default: false

Add TPM device

Array of objects (NetworkCreateConfig)

Network configurations

Array of objects (EnhancedGraphicsConfig)

Graphics device configurations

Array of objects (PCIDeviceConfig)

PCI devices for passthrough

object (CloudInit)

Cloud-init configuration for VM initialization

template
string

Template name to base VM on

autostart
boolean
Default: false

Start VM automatically on host boot

custom_xml
string

Custom libvirt XML snippet to merge

object

Custom metadata key-value pairs

Responses

Request samples

Content type
application/json
{
  • "name": "web-server-01",
  • "memory": 4096,
  • "vcpus": 2,
  • "max_memory": 8192,
  • "max_vcpus": 4,
  • "cpu": {
    },
  • "storage": {
    },
  • "os_type": "linux",
  • "os_variant": "ubuntu20.04",
  • "os_info": {
    },
  • "architecture": "x86_64",
  • "machine_type": "q35",
  • "uefi": false,
  • "secure_boot": false,
  • "tpm": false,
  • "networks": [
    ],
  • "graphics": [
    ],
  • "pci_devices": [
    ],
  • "cloud_init": {
    },
  • "template": "ubuntu-server-template",
  • "autostart": false,
  • "custom_xml": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get virtual machine details

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update a virtual machine

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Request Body schema: application/json
required
name
required
string

Name of the virtual machine

memory
required
integer >= 256

Memory size in MB

vcpus
required
integer [ 1 .. 256 ]

Number of virtual CPUs

max_memory
integer >= 0

Maximum memory limit in MB (0 = same as memory)

max_vcpus
integer [ 0 .. 256 ]

Maximum vCPU limit (0 = same as vcpus)

object

Optional CPU model and topology configuration. If omitted, Vapor uses a simple topology-only CPU element:

required
object (StorageConfig)
os_type
string

Operating system type

os_variant
string

Operating system variant

object (OSInfoEnhanced)

Detailed OS information for metadata and optimization

architecture
string
Default: "x86_64"

System architecture

machine_type
string
Default: "q35"

Machine type (q35, pc, virt, etc)

uefi
boolean
Default: false

Use UEFI boot

secure_boot
boolean
Default: false

Enable secure boot

tpm
boolean
Default: false

Add TPM device

Array of objects (NetworkCreateConfig)

Network configurations

Array of objects (EnhancedGraphicsConfig)

Graphics device configurations

Array of objects (PCIDeviceConfig)

PCI devices for passthrough

object (CloudInit)

Cloud-init configuration for VM initialization

template
string

Template name to base VM on

autostart
boolean
Default: false

Start VM automatically on host boot

custom_xml
string

Custom libvirt XML snippet to merge

object

Custom metadata key-value pairs

Responses

Request samples

Content type
application/json
{
  • "name": "web-server-01",
  • "memory": 4096,
  • "vcpus": 2,
  • "max_memory": 8192,
  • "max_vcpus": 4,
  • "cpu": {
    },
  • "storage": {
    },
  • "os_type": "linux",
  • "os_variant": "ubuntu20.04",
  • "os_info": {
    },
  • "architecture": "x86_64",
  • "machine_type": "q35",
  • "uefi": false,
  • "secure_boot": false,
  • "tpm": false,
  • "networks": [
    ],
  • "graphics": [
    ],
  • "pci_devices": [
    ],
  • "cloud_init": {
    },
  • "template": "ubuntu-server-template",
  • "autostart": false,
  • "custom_xml": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "string",
  • "data": {
    }
}

Delete a virtual machine

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

query Parameters
remove_disks
boolean

Whether to remove associated storage disks

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Perform action on virtual machine

Execute various state-changing actions on a virtual machine. Available actions include: start, stop, restart, pause, resume, reset. Use the 'force' flag for forced stop or restart operations.

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Request Body schema: application/json
required
action
required
string
Enum: "start" "stop" "force-stop" "destroy" "restart" "pause" "resume" "reset"

The action to perform on the virtual machine

force
boolean
Default: false

Force the action (applicable for stop and restart). Note - use force-stop or destroy action for immediate forceful shutdown.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "start",
  • "force": false
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Clone a virtual machine

Clone an existing virtual machine to a new VM.

Notes:

  • Only full clones are currently supported.
  • Snapshot cloning is not supported.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: web-server-01

Source VM name or UUID

Request Body schema: application/json
required
name
required
string

Name of the new cloned VM

full_clone
boolean
Default: true

Whether to create a full clone instead of a linked clone

snapshots
boolean
Default: false

Whether to clone snapshots as well (currently not supported)

storage_pool
string

Optional target storage pool for the cloned disks

Responses

Request samples

Content type
application/json
Example
{
  • "name": "web-server-01-clone"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Set VM network interface link state

Change the link state of a virtual machine's network interface to disconnect (down) or reconnect (up). This is equivalent to the virsh commands:

  • virsh domif-setlink <domain> <interface> down - to disconnect
  • virsh domif-setlink <domain> <interface> up - to reconnect

The interface can be identified by either:

  • Interface name (e.g., "vnet0", "vnet1")
  • MAC address (e.g., "52:54:00:12:34:56")
Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Request Body schema: application/json
required
interface
required
string

The network interface identifier. Can be either:

  • Interface device name (e.g., "vnet0", "vnet1", "eth0")
  • MAC address (e.g., "52:54:00:12:34:56")
state
required
string
Enum: "up" "down"

The desired link state

Responses

Request samples

Content type
application/json
Example
{
  • "interface": "vnet0",
  • "state": "down"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "Network interface vnet0 link state changed to down",
  • "interface": "vnet0",
  • "state": "down",
  • "mac": "52:54:00:12:34:56"
}

Get VM network interface link state

Retrieve the current link state of a virtual machine's network interface. This is equivalent to the virsh command:

  • virsh domif-getlink <domain> <interface> - to check link state

The interface can be identified by either:

  • Interface name (e.g., "vnet0", "vnet1")
  • MAC address (e.g., "52:54:00:12:34:56")

Returns "up" if the interface is connected or "down" if disconnected. If no explicit link state is set, the default is "up".

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

interface-name
required
string

Network interface name (e.g., "vnet0") or MAC address

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "message": "Network interface vnet0 link state retrieved",
  • "interface": "vnet0",
  • "state": "up",
  • "mac": "52:54:00:12:34:56"
}

Migrate VM to another host

Initiate live or offline migration of a virtual machine to another host.

Prerequisites for SSH-based Migration:

When using SSH transport (e.g., qemu+ssh://host2.example.com/system):

  1. SSH Key Authentication Required:

    • The source host must have passwordless SSH access to the destination host
    • The user running libvirtd (typically root or libvirt) needs SSH keys configured

  2. Setup Steps:

    # On source host (as root or libvirt user):
ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
ssh-copy-id root@destination-host

# Verify connectivity:
ssh root@destination-host 'virsh list'

  3. Both Hosts Requirements:

    • Same libvirt version (recommended)
    • Compatible CPU architectures
    • Shared storage (for disk migration) or use copy_storage parameter
    • Network connectivity between hosts
    • Sufficient resources on destination host

  4. Alternative Transport Options:

    • qemu+tcp:// - Unencrypted TCP (not recommended)
    • qemu+tls:// - TLS with certificates (more secure for production)
    • qemu+ssh://user@host/system - SSH with specific user

  5. Security Best Practices:

    • Use dedicated service accounts instead of root
    • Restrict SSH keys to libvirt commands only
    • Consider TLS for production environments
    • Ensure firewall rules allow migration traffic
Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Request Body schema: application/json
required
destination_host
required
string

Target host for migration. The host must be accessible via the transport method specified in destination_uri (SSH by default).

For SSH transport, passwordless SSH access must be configured from source to destination host.

destination_uri
string

Optional custom libvirt URI for destination. Common formats:

  • qemu+ssh://host2.example.com/system - SSH transport (default, requires SSH keys)
  • qemu+ssh://user@host2.example.com/system - SSH with specific user
  • qemu+tcp://host2.example.com/system - TCP transport (unencrypted, not recommended)
  • qemu+tls://host2.example.com/system - TLS transport (requires certificates)

SSH Requirements: The source host must have passwordless SSH access to the destination. SSH public key of the source host's libvirt user (usually root) must be in the destination host's authorized_keys file.

Setup Example:

# On source host as root:
ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
ssh-copy-id root@host2.example.com
live
boolean
Default: true

Perform live migration (VM stays running during migration). Requires stable network connection and compatible hosts.

tunneled
boolean
Default: false

Use tunneled migration. All migration data goes through the libvirt connection. More secure but potentially slower.

compressed
boolean
Default: false

Enable compression during migration. Reduces network bandwidth usage but increases CPU usage on both hosts.

auto_converge
boolean
Default: false

Enable auto-convergence to speed up migration. Automatically throttles VM CPU usage if migration is not converging.

allow_unsafe
boolean
Default: false

Allow unsafe migration operations. Use with caution as it may result in VM crashes or data corruption if hosts are incompatible.

max_bandwidth
integer
Default: 0

Maximum bandwidth in MB/s for migration (0 for unlimited). Useful to prevent migration from saturating network links.

max_downtime
integer
Default: 500

Maximum allowed downtime in milliseconds during live migration. Lower values mean less interruption but migration may take longer.

copy_storage
string
Default: "none"
Enum: "none" "all" "inc"

Storage migration mode:

  • none: No storage migration (requires shared storage)
  • all: Copy all disk images to destination
  • inc: Copy only incremental changes (for supported formats)

Note: Storage migration significantly increases migration time.

Responses

Request samples

Content type
application/json
{
  • "destination_host": "host2.example.com",
  • "destination_uri": "qemu+ssh://host2.example.com/system",
  • "live": true,
  • "tunneled": false,
  • "compressed": false,
  • "auto_converge": false,
  • "allow_unsafe": false,
  • "max_bandwidth": 100,
  • "max_downtime": 500,
  • "copy_storage": "none"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get migration status

Check the status of an ongoing VM migration

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

query Parameters
migration_id
string

Migration ID to check status for

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get VM console information

Retrieves console connection information for a virtual machine and generates a secure access token. The token is valid for a limited time (default 5 minutes) and can only be used once.

Authorizations:
bearerAuth
path Parameters
id
required
string

VM ID (name or UUID)

query Parameters
type
string
Default: "vnc"
Enum: "vnc" "spice"

Console type preference

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

WebSocket console connection

Establishes a WebSocket connection for VM console access. This endpoint upgrades the HTTP connection to a WebSocket connection and proxies data between the client and the VM's VNC/SPICE server.

Protocol: WebSocket (ws:// or wss://)

Data Flow: Binary frames containing VNC/SPICE protocol data

Error Messages: JSON messages for errors and status updates

Authorizations:
bearerAuth
path Parameters
id
required
string

VM ID (name or UUID)

query Parameters
token
required
string

Access token from console information endpoint

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get console connection statistics

Retrieves statistics about active console connections for monitoring and debugging purposes.

Authorizations:
bearerAuth
path Parameters
id
required
string

VM ID (name or UUID)

Responses

Response samples

Content type
application/json
{
  • "active_connections": 0,
  • "total_bytes_sent": 0,
  • "total_bytes_received": 0,
  • "connections": [
    ]
}

Get available console types

Returns information about all available console types for the specified virtual machine. This includes VNC and SPICE console availability based on VM configuration.

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get VNC console information

Returns VNC-specific console connection information for the virtual machine. Use this endpoint to get VNC server details before establishing a WebSocket connection.

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

VNC WebSocket console connection

Establishes a WebSocket connection for VNC console access to the virtual machine.

WebSocket Protocol:

  • Upgrade: websocket
  • Connection: Upgrade
  • Subprotocol: binary (for VNC RFB protocol)

Authentication:

  • Bearer token should be passed as query parameter: ?token=<jwt_token>
  • Or via WebSocket subprotocol: Sec-WebSocket-Protocol: access_token, <jwt_token>
Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

query Parameters
token
string

JWT authentication token (alternative to header auth)

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get SPICE console information

Returns SPICE-specific console connection information for the virtual machine. Use this endpoint to get SPICE server details before establishing a WebSocket connection.

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

SPICE WebSocket console connection

Establishes a WebSocket connection for SPICE console access to the virtual machine.

WebSocket Protocol:

  • Upgrade: websocket
  • Connection: Upgrade
  • Subprotocol: binary (for SPICE protocol)

Authentication:

  • Bearer token should be passed as query parameter: ?token=<jwt_token>
  • Or via WebSocket subprotocol: Sec-WebSocket-Protocol: access_token, <jwt_token>
Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

query Parameters
token
string

JWT authentication token (alternative to header auth)

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get VM performance metrics

Retrieves current performance metrics for a virtual machine including CPU, memory, disk I/O, and network statistics.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: vm01

VM ID (name or UUID)

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Stream VM metrics via WebSocket

Establishes a WebSocket connection to stream real-time performance metrics for a virtual machine. The server sends metrics at regular intervals as JSON messages. Protocol: WebSocket (ws:// or wss://) Message Format: JSON objects containing VMMetrics data Default Interval: 5 seconds (configurable via query parameter) Client Messages: Send any message to keep connection alive (ping/pong) Server Messages: VMMetrics objects or error messages in JSON format

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: vm01

VM ID (name or UUID)

query Parameters
interval
integer >= 1
Default: 5
Example: interval=5

Metrics update interval in seconds (minimum 1, default 5)

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": "string"
}

List available PCI devices

List all PCI devices available for passthrough to virtual machines. This includes GPUs, network cards, storage controllers, USB controllers, and other PCI devices.

Prerequisites:

  • IOMMU must be enabled in BIOS/UEFI and kernel
  • Devices must be in separate IOMMU groups for passthrough
  • vfio-pci driver must be loaded
Authorizations:
bearerAuth
query Parameters
type
string
Enum: "gpu" "network" "storage" "usb" "other"

Filter devices by type

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Attach PCI device to VM

Attach a PCI device to a virtual machine for passthrough.

Important Notes:

  • VM must be powered off for initial PCI passthrough setup
  • All devices in the same IOMMU group must be passed through together
  • Device will be unbound from host driver and bound to vfio-pci
  • For GPUs, consider passing through audio device as well
Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Request Body schema: application/json
required
device_id
required
string

PCI device identifier to attach

object

VFIO driver options

managed
boolean
Default: true

Let libvirt manage device binding

Responses

Request samples

Content type
application/json
{
  • "device_id": "pci_0000_01_00_0",
  • "vfio_options": {
    },
  • "managed": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Detach PCI device from VM

Detach a PCI device from a virtual machine.

Notes:

  • VM should be powered off for safe removal
  • Device will be unbound from vfio-pci and may rebind to original driver
Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

device_id
required
string

PCI device ID (e.g., pci_0000_01_00_0)

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Hotplug resources to VM

Dynamically add or remove resources to/from a running virtual machine.

Supported Resources:

  • CPU: Add vCPUs (removal not supported on most guests)
  • Memory: Add memory (removal requires guest support)
  • Disk: Add/remove storage devices
  • Network: Add/remove network interfaces
  • USB: Add/remove USB devices

Requirements:

  • VM must be running for hotplug operations
  • Guest OS must support hotplug for the resource type
  • ACPI hotplug must be enabled in VM configuration
Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Request Body schema: application/json
required
resource_type
required
string
Enum: "cpu" "memory" "disk" "network" "usb"

Type of resource to hotplug

action
required
string
Enum: "add" "remove"

Action to perform

required
HotplugCPUConfig (object) or HotplugMemoryConfig (object) or HotplugDiskConfig (object) or HotplugNetworkConfig (object) or HotplugUSBConfig (object)

Resource-specific configuration

Responses

Request samples

Content type
application/json
{
  • "resource_type": "cpu",
  • "action": "add",
  • "configuration": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Check VM snapshot capabilities

Check what snapshot operations are supported for a VM based on its disk formats.

This endpoint analyzes all disks attached to the VM and determines:

  • Whether internal snapshots are supported (requires all disks to be qcow2)
  • Whether external snapshots are supported (always supported)
  • Whether memory snapshots are supported (requires qcow2 for all disks)
  • Disk format limitations and recommendations
Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List VM snapshots

Retrieve all snapshots for a specific virtual machine

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create VM snapshot with enhanced format checking

Create a new snapshot of a virtual machine with enhanced disk format validation.

This endpoint performs comprehensive format checking for all VM disks and determines the appropriate snapshot type based on disk formats and user preferences.

Snapshot Types:

  • Internal: All disk states stored within existing disk files (requires all disks to be qcow2)
  • External: Creates new files for disk states (supports any disk format)
  • Internal-Memory: Internal snapshot with memory state (requires qcow2 and running VM)

Format Requirements:

  • Internal snapshots: All disks must be qcow2 format
  • External snapshots: Works with any disk format (raw, qcow2, vmdk, etc.)
  • Memory snapshots: Requires qcow2 format for all disks

Validation Checks:

  • Disk format compatibility
  • VM state compatibility
  • Storage availability
  • Guest agent availability (for quiesce)

Warning Conditions:

  • Mixed disk formats detected
  • Raw format disks requiring external snapshots
  • Large memory state warnings
  • Quiesce requested but guest agent unavailable

Best Practices:

  • Use quiesce for database workloads when guest agent is available
  • Consider external snapshots for mixed format environments
  • Monitor storage space before creating snapshots
  • Test snapshot restoration in non-production first
Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Name for the snapshot

description
string <= 1024 characters

Optional description of the snapshot

include_memory
boolean
Default: false

Include memory state in the snapshot.

  • true: Full system state including RAM (VM must be running)
  • false: Disk-only snapshot (VM can be running or stopped)
quiesce
boolean
Default: false

Quiesce the VM filesystem before snapshot (requires guest agent). This ensures filesystem consistency by flushing buffers.

Responses

Request samples

Content type
application/json
{
  • "name": "before-upgrade",
  • "description": "Snapshot taken before system upgrade",
  • "include_memory": true,
  • "quiesce": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get snapshot details

Retrieve details of a specific VM snapshot

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

snapshot
required
string

Snapshot name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete VM snapshot

Delete a specific snapshot of a virtual machine

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

snapshot
required
string

Snapshot name to delete

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Revert to snapshot

Revert a virtual machine to a previous snapshot state.

Warning: This operation will:

  • Discard all changes made since the snapshot was taken
  • Restore the VM to the exact state when the snapshot was created
  • Cannot be undone without another snapshot

Revert Behavior: By default (flags=1), running VMs will stay running after revert. This is a live revert that only works for disk-only snapshots. If the snapshot includes memory state, libvirt must restore that memory, which effectively restarts the VM.

You can control the revert behavior using the flags parameter in the request body.

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

snapshot
required
string

Snapshot name to revert to

Request Body schema: application/json
optional

Optional revert configuration

flags
integer <uint32>
Default: 1

Libvirt snapshot revert flags to control revert behavior.

Available flags:

  • 0: Default libvirt behavior (may restart the VM)
  • 1: DOMAIN_SNAPSHOT_REVERT_RUNNING (keep domain running after revert - default)
  • 2: DOMAIN_SNAPSHOT_REVERT_PAUSED (leave domain paused after revert)
  • 4: DOMAIN_SNAPSHOT_REVERT_FORCE (force revert even if risky)

Flags can be combined using bitwise OR.

Default: 1 (DOMAIN_SNAPSHOT_REVERT_RUNNING) - keeps running VMs running.

Responses

Request samples

Content type
application/json
Example
{
  • "flags": 1
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List VM backups

List all backups for a specific virtual machine

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create VM backup

Create a backup of a virtual machine.

Backup Types:

  • full: Complete backup of all VM disks
  • incremental: Only changes since last backup
  • differential: Changes since last full backup

Options:

  • Compression (gzip, bzip2, xz, zstd)
  • Encryption (AES-256, AES-128)
  • Include memory state
  • Custom retention period
Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Request Body schema: application/json
required
backup_type
string
Default: "full"
Enum: "full" "incremental" "differential"

Type of backup

destination_path
required
string

Where to store the backup

compression
string
Default: "none"
Enum: "none" "gzip" "bzip2" "xz" "zstd"

Compression type

encryption
string
Default: "none"
Enum: "none" "AES-256" "AES-128"

Encryption type

encryption_key
string

Encryption key (required if encryption is enabled)

include_memory
boolean
Default: false

Include memory state in backup

retention_days
integer
Default: 30

Number of days to retain the backup

description
string

Optional description of the backup

Responses

Request samples

Content type
application/json
{
  • "backup_type": "full",
  • "destination_path": "/backup/vms/",
  • "compression": "gzip",
  • "encryption": "AES-256",
  • "encryption_key": "my-secret-key-123",
  • "include_memory": true,
  • "retention_days": 90,
  • "description": "Weekly backup before maintenance"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Restore VM from backup

Restore a virtual machine from a backup.

Options:

  • Restore to new VM with different name
  • Overwrite existing VM
  • Decrypt encrypted backups
Authorizations:
bearerAuth
Request Body schema: application/json
required
backup_id
required
string

ID of the backup to restore from

new_vm_name
string

Name for the restored VM (optional, uses original name if not specified)

overwrite
boolean
Default: false

Whether to overwrite existing VM with same name

decryption_key
string

Decryption key (required if backup is encrypted)

restore_memory
boolean
Default: true

Whether to restore memory state (if available)

storage_pool
string

Storage pool to restore VM disks to

Responses

Request samples

Content type
application/json
{
  • "backup_id": "backup-123456",
  • "new_vm_name": "web-server-01-restored",
  • "overwrite": false,
  • "decryption_key": "my-secret-key-123",
  • "restore_memory": true,
  • "storage_pool": "default"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete VM backup

Delete a specific VM backup

Authorizations:
bearerAuth
path Parameters
backup_id
required
string

Backup ID

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

List VM templates

List all available VM templates

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create VM template

Create a new VM template

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Template name (unique)

description
string

Template description

os_type
required
string
Enum: "linux" "windows" "bsd" "other" "hvm"

Operating system type

os_variant
string

libosinfo / libvirt OS variant identifier

min_memory
required
integer

Minimum memory in MB

recommended_memory
integer

Recommended memory in MB (must be >= min_memory when provided)

min_vcpus
required
integer

Minimum vCPUs

recommended_vcpus
integer

Recommended vCPUs (must be >= min_vcpus when provided)

min_disk
required
integer

Minimum disk size in GB

recommended_disk
integer

Recommended disk size in GB (must be >= min_disk when provided)

disk_format
string
Default: "qcow2"
Enum: "qcow2" "raw" "vmdk" "qed" "vdi"

Disk image format to use for created disks

network_model
string
Default: "virtio"
Enum: "virtio" "e1000" "rtl8139"

Recommended network model

graphics_type
string
Default: "vnc"
Enum: "vnc" "spice" "none" "egl-headless"

Graphics type

cloud_init
boolean

Whether the template supports cloud-init

uefi_boot
boolean

Whether to use UEFI boot by default

secure_boot
boolean

Whether to enable secure boot by default

tpm
boolean

Whether to add a TPM device by default

default_user
string

Default username to use when generating cloud-init user configuration

object

Additional metadata

Responses

Request samples

Content type
application/json
{
  • "name": "ubuntu-22.04",
  • "description": "Ubuntu 22.04 LTS template",
  • "os_type": "linux",
  • "os_variant": "ubuntu22.04",
  • "min_memory": 2048,
  • "recommended_memory": 4096,
  • "min_vcpus": 2,
  • "recommended_vcpus": 4,
  • "min_disk": 20,
  • "recommended_disk": 50,
  • "disk_format": "qcow2",
  • "network_model": "virtio",
  • "graphics_type": "vnc",
  • "cloud_init": true,
  • "uefi_boot": true,
  • "secure_boot": false,
  • "tpm": false,
  • "default_user": "ubuntu",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get VM template details

Get detailed information about a specific VM template

Authorizations:
bearerAuth
path Parameters
id
required
integer

Template ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update VM template

Update an existing VM template

Authorizations:
bearerAuth
path Parameters
id
required
integer

Template ID

Request Body schema: application/json
required
description
string

Template description

os_type
string
Enum: "linux" "windows" "bsd" "other" "hvm"

Operating system type

os_variant
string

libosinfo / libvirt OS variant identifier

min_memory
integer

Minimum memory in MB

recommended_memory
integer

Recommended memory in MB (must be >= min_memory when provided)

min_vcpus
integer

Minimum vCPUs

recommended_vcpus
integer

Recommended vCPUs (must be >= min_vcpus when provided)

min_disk
integer

Minimum disk size in GB

recommended_disk
integer

Recommended disk size in GB (must be >= min_disk when provided)

disk_format
string
Enum: "qcow2" "raw" "vmdk" "qed" "vdi"

Disk image format to use for created disks

network_model
string
Enum: "virtio" "e1000" "rtl8139"

Recommended network model

graphics_type
string
Enum: "vnc" "spice" "none" "egl-headless"

Graphics type

cloud_init
boolean

Whether the template supports cloud-init

uefi_boot
boolean

Whether to use UEFI boot by default

secure_boot
boolean

Whether to enable secure boot by default

tpm
boolean

Whether to add a TPM device by default

default_user
string

Default username to use when generating cloud-init user configuration

object

Additional metadata

Responses

Request samples

Content type
application/json
{
  • "description": "Updated Ubuntu 22.04 LTS template",
  • "os_type": "linux",
  • "os_variant": "ubuntu22.04",
  • "min_memory": 2048,
  • "recommended_memory": 4096,
  • "min_vcpus": 2,
  • "recommended_vcpus": 4,
  • "min_disk": 20,
  • "recommended_disk": 50,
  • "disk_format": "qcow2",
  • "network_model": "virtio",
  • "graphics_type": "vnc",
  • "cloud_init": true,
  • "uefi_boot": true,
  • "secure_boot": false,
  • "tpm": false,
  • "default_user": "ubuntu",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete VM template

Delete a VM template from the system

Authorizations:
bearerAuth
path Parameters
id
required
integer

Template ID

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Create VM template from existing VM

Create a new VM template by extracting sizing and configuration defaults from an existing VM.

The backend derives the template fields from the VM's enhanced details (memory, vCPUs, disk, OS info, graphics, cloud-init detection, UEFI/SecureBoot/TPM flags).

Authorizations:
bearerAuth
path Parameters
id
required
string

VM name or UUID

Request Body schema: application/json
required
name
required
string

New template name (unique)

description
string

Template description

Responses

Request samples

Content type
application/json
{
  • "name": "web-server-template",
  • "description": "Template derived from VM web-server-01"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create VM from template

Create a new virtual machine using a predefined template.

The template provides base specifications including minimum and recommended values for memory, vCPUs, and disk size. User-provided values will override template recommendations but must meet minimum requirements.

Template Application:

  • If user values are not provided, template recommended values are used
  • If template has no recommendation, minimum values are used
  • User values are validated against template minimum requirements
  • Template settings for OS, network, graphics, and cloud-init are applied
Authorizations:
bearerAuth
Request Body schema: application/json
required
template_id
required
integer

Template ID to use for VM creation

name
required
string

Name for the new VM

memory
integer

Memory in MB (overrides template recommendation, must meet minimum)

vcpus
integer

Number of vCPUs (overrides template recommendation, must meet minimum)

disk_size
integer

Disk size in GB (overrides template recommendation, must meet minimum)

object

Network configuration (overrides template defaults)

object

Graphics configuration (overrides template defaults)

object

Cloud-init configuration (if template supports cloud-init)

object

Additional metadata for the VM

Responses

Request samples

Content type
application/json
{
  • "template_id": 1,
  • "name": "my-ubuntu-vm",
  • "memory": 4096,
  • "vcpus": 2,
  • "disk_size": 50,
  • "network": {
    },
  • "graphics": {
    },
  • "cloud_init": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Auth

Authenticate user

Authenticate a user and receive a JWT token.

Authentication Methods:

  • Password: Use Linux system user credentials
  • SSH Key: Use SSH private key for authentication

The auth_type field determines the authentication method.

Request Body schema: application/json
required
username
required
string

Username for authentication

password
string

User password (required for password auth)

auth_type
string
Default: "password"
Enum: "password" "ssh_key"

Authentication type

ssh_signature
string

SSH signature for key-based auth

challenge
string

Challenge string for SSH key auth

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string",
  • "auth_type": "password",
  • "ssh_signature": "string",
  • "challenge": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Refresh JWT token

Refresh an existing JWT token. Supports refreshing expired tokens within a 7-day grace period.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create SSH authentication challenge

Create a challenge for SSH key-based authentication. The challenge must be signed with the user's private key.

Request Body schema: application/json
required
username
required
string

Username requesting the challenge

key_fingerprint
string

Optional SSH key fingerprint to use

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "key_fingerprint": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Verify SSH challenge signature

Verify a signed SSH challenge to complete authentication. Returns a JWT token upon successful verification.

Request Body schema: application/json
required
username
required
string

Username

challenge
required
string

Original challenge string

signature
required
string

Base64-encoded signature of the challenge

key_type
string
Enum: "rsa" "ed25519" "ecdsa"

SSH key type

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "challenge": "string",
  • "signature": "string",
  • "key_type": "rsa"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get user's SSH public keys

Retrieve the authorized SSH public keys for a specific user. Reads from the user's ~/.ssh/authorized_keys file.

path Parameters
username
required
string

Username to get keys for

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List API tokens

List all API tokens for the authenticated user

Authorizations:
bearerAuthNone

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Create API token

Create a new API token

Authorizations:
bearerAuthNone
Request Body schema: application/json
required
name
required
string

Friendly name for the token

expires_at
string <date-time>

Optional expiration time for the token

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get current token details

Get detailed information about the token used for the current request

Authorizations:
bearerAuthNone

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get API token details

Get details of a specific API token

Authorizations:
bearerAuthNone
path Parameters
id
required
string

ID of the token

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Revoke API token

Revoke (delete) an API token

Authorizations:
bearerAuthNone
path Parameters
id
required
string

ID of the token

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "Token revoked"
}

Network

List network interface types

Returns a list of unique network interface types available on the system

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List network interfaces

List network interfaces with optional filtering by type.

Authorizations:
bearerAuth
query Parameters
type
string
Example: type=bridge,device

Filter interfaces by type (comma-separated for multiple types). Examples: bridge, device, vlan, bond, veth, tun, tap, dummy.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get network interface details

Authorizations:
bearerAuth
path Parameters
name
required
string

Interface name

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Bring interface up

Authorizations:
bearerAuth
path Parameters
name
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Bring interface down

Authorizations:
bearerAuth
path Parameters
name
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Configure IP address

Authorizations:
bearerAuth
path Parameters
name
required
string
Request Body schema: application/json
required
address
required
string <ipv4>
netmask
required
integer [ 0 .. 32 ]
gateway
string <ipv4>

Responses

Request samples

Content type
application/json
{
  • "address": "192.168.0.1",
  • "netmask": 32,
  • "gateway": "192.168.0.1"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update IP address

Authorizations:
bearerAuth
path Parameters
name
required
string
Request Body schema: application/json
required
address
required
string <ipv4>
netmask
required
integer [ 0 .. 32 ]
gateway
string <ipv4>

Responses

Request samples

Content type
application/json
{
  • "address": "192.168.0.1",
  • "netmask": 32,
  • "gateway": "192.168.0.1"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete IP address

Authorizations:
bearerAuth
path Parameters
name
required
string
query Parameters
address
required
string <ipv4>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List network bridges

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Create network bridge

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
interfaces
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "interfaces": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get network bridge details

Authorizations:
bearerAuth
path Parameters
name
required
string

Bridge name

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update network bridge

Updates bridge configuration by removing old members and adding new ones

Authorizations:
bearerAuth
path Parameters
name
required
string

Bridge name

Request Body schema: application/json
required
name
required
string
interfaces
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "interfaces": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete network bridge

Authorizations:
bearerAuth
path Parameters
name
required
string

Bridge name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List network bonds

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Create network bond

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
mode
required
string
interfaces
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "mode": "string",
  • "interfaces": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update network bond

Updates bond configuration by removing old members and adding new ones

Authorizations:
bearerAuth
path Parameters
name
required
string

Bond name

Request Body schema: application/json
required
name
required
string
mode
required
string
interfaces
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "mode": "string",
  • "interfaces": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete network bond

Authorizations:
bearerAuth
path Parameters
name
required
string

Bond name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List VLAN interfaces

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Create VLAN interface

Authorizations:
bearerAuth
Request Body schema: application/json
required
interface
required
string
vlan_id
required
integer [ 1 .. 4094 ]
name
string

Responses

Request samples

Content type
application/json
{
  • "interface": "string",
  • "vlan_id": 1,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update network VLAN

Updates VLAN configuration using delete and recreate pattern to change VLAN ID

Authorizations:
bearerAuth
path Parameters
name
required
string

VLAN name

Request Body schema: application/json
required
interface
required
string
vlan_id
required
integer [ 1 .. 4094 ]
name
string

Responses

Request samples

Content type
application/json
{
  • "interface": "string",
  • "vlan_id": 1,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete network VLAN

Authorizations:
bearerAuth
path Parameters
name
required
string

VLAN name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get Open vSwitch status

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List Open vSwitch bridges

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create Open vSwitch bridge

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
fail_mode
string
Enum: "secure" "standalone"
stp_enable
boolean
rstp_enable
boolean
datapath_type
string
protocols
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "br-int",
  • "fail_mode": "secure",
  • "stp_enable": false,
  • "rstp_enable": false,
  • "datapath_type": "system",
  • "protocols": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get Open vSwitch bridge details

Authorizations:
bearerAuth
path Parameters
name
required
string

OVS bridge name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update Open vSwitch bridge

Authorizations:
bearerAuth
path Parameters
name
required
string

OVS bridge name

Request Body schema: application/json
required
fail_mode
string
Enum: "secure" "standalone"
stp_enable
boolean
rstp_enable
boolean
datapath_type
string
protocols
Array of strings

Responses

Request samples

Content type
application/json
{
  • "fail_mode": "standalone",
  • "stp_enable": true,
  • "rstp_enable": false,
  • "datapath_type": "netdev",
  • "protocols": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete Open vSwitch bridge

Authorizations:
bearerAuth
path Parameters
name
required
string

OVS bridge name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List Open vSwitch bridge ports

Authorizations:
bearerAuth
path Parameters
name
required
string

OVS bridge name

query Parameters
type
string

Filter ports by OVS port type (for example system, internal, patch, vxlan, dpdk, tap, geneve, gre)

service_tags
string
Example: service_tags=management,storage

Filter ports by service tags using a comma-separated list (supported values are management, migration, shared-heartbeat, storage, replication, backup). A port must contain all requested tags.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get Open vSwitch bridge topology

Authorizations:
bearerAuth
path Parameters
name
required
string

OVS bridge name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List Open vSwitch ports

Authorizations:
bearerAuth
query Parameters
type
string

Filter ports by OVS port type (for example system, internal, patch, vxlan, dpdk, tap, geneve, gre)

service_tags
string
Example: service_tags=management,storage

Filter ports by service tags using a comma-separated list (supported values are management, migration, shared-heartbeat, storage, replication, backup). A port must contain all requested tags.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create Open vSwitch port

Authorizations:
bearerAuth
Request Body schema: application/json
required
bridge
required
string
name
required
string
type
string
interfaces
Array of strings
tag
integer [ 0 .. 4094 ]
trunks
Array of integers
vlan_mode
string
bond_mode
string
lacp
string
peer
string
service_tags
Array of strings
Items Enum: "management" "migration" "shared-heartbeat" "storage" "replication" "backup"
mtu_request
integer

Responses

Request samples

Content type
application/json
{
  • "bridge": "br-int",
  • "name": "patch-int",
  • "type": "patch",
  • "interfaces": [
    ],
  • "tag": 120,
  • "trunks": [
    ],
  • "vlan_mode": "access",
  • "bond_mode": "active-backup",
  • "lacp": "active",
  • "peer": "patch-ext",
  • "service_tags": [
    ],
  • "mtu_request": 1450
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get Open vSwitch port details

Authorizations:
bearerAuth
path Parameters
name
required
string

OVS port name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update Open vSwitch port

Authorizations:
bearerAuth
path Parameters
name
required
string

OVS port name

Request Body schema: application/json
required
bridge
string
type
string
interfaces
Array of strings
tag
integer [ 0 .. 4094 ]
trunks
Array of integers
vlan_mode
string
bond_mode
string
lacp
string
peer
string
service_tags
Array of strings
Items Enum: "management" "migration" "shared-heartbeat" "storage" "replication" "backup"
mtu_request
integer

Responses

Request samples

Content type
application/json
{
  • "bridge": "br-int",
  • "type": "internal",
  • "interfaces": [
    ],
  • "tag": 200,
  • "trunks": [
    ],
  • "vlan_mode": "trunk",
  • "bond_mode": "balance-slb",
  • "lacp": "passive",
  • "peer": "patch-ext",
  • "service_tags": [
    ],
  • "mtu_request": 1500
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete Open vSwitch port

Authorizations:
bearerAuth
path Parameters
name
required
string

OVS port name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Storage

List storage disks

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Mount filesystem

Authorizations:
bearerAuth
Request Body schema: application/json
required
device
required
string
mount_point
required
string
filesystem
string
options
string

Responses

Request samples

Content type
application/json
{
  • "device": "string",
  • "mount_point": "string",
  • "filesystem": "string",
  • "options": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Unmount filesystem

Authorizations:
bearerAuth
Request Body schema: application/json
required
mount_point
required
string
force
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "mount_point": "string",
  • "force": false
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Format disk

Authorizations:
bearerAuth
Request Body schema: application/json
required
device
required
string
filesystem
required
string
Enum: "ext4" "ext3" "ext2" "xfs" "btrfs"
label
string

Responses

Request samples

Content type
application/json
{
  • "device": "string",
  • "filesystem": "ext4",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List LVM volume groups

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List LVM logical volumes

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List LVM physical volumes

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create LVM volume group

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
devices
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "devices": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create LVM logical volume

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
vg_name
required
string
size
required
string
filesystem
string
Enum: "ext4" "ext3" "ext2" "xfs" "btrfs"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "vg_name": "string",
  • "size": "string",
  • "filesystem": "ext4"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List multipath paths

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List BTRFS subvolumes

Authorizations:
bearerAuth
query Parameters
mount_point
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create BTRFS subvolume

Authorizations:
bearerAuth
Request Body schema: application/json
required
path
required
string

Responses

Request samples

Content type
application/json
{
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete BTRFS subvolume

Authorizations:
bearerAuth
Request Body schema: application/json
required
path
required
string

Responses

Request samples

Content type
application/json
{
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create BTRFS snapshot

Authorizations:
bearerAuth
Request Body schema: application/json
required
source
required
string
destination
required
string

Responses

Request samples

Content type
application/json
{
  • "source": "string",
  • "destination": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List RAID devices

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get available disks for RAID

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create RAID device

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Name of the RAID device (e.g., raid0)

level
required
string
Enum: "0" "1" "5" "6" "10"

RAID level

disks
required
Array of strings >= 2 items

List of disk paths to use for RAID

chunk_size
string
Default: "512K"

Chunk size (e.g., 512K, 1M)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "level": "0",
  • "disks": [
    ],
  • "chunk_size": "512K"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Destroy RAID device

Authorizations:
bearerAuth
Request Body schema: application/json
required
device
required
string

RAID device path to destroy

Responses

Request samples

Content type
application/json
{
  • "device": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Container

List containers

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create container

Create a new container using the CRI runtime

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
string

Optional container name

image
string

Docker image to use for the container

cmd
Array of strings

Command to run in the container

entrypoint
Array of strings

Override the image entrypoint

env
Array of strings

List of environment variables to set in the container

object

Ports to expose from the container

object

Port mappings for exposed container ports

object

Metadata labels assigned to the container

workingDir
string

Working directory in the container

Array of objects
networkMode
string

Which network to connect container to

cgroupParent
string

Optional cgroup parent for the CRI sandbox (cgroupfs style, e.g., /system.slice).

object

Resource limits for the container

object

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my-nginx",
  • "image": "nginx:latest",
  • "env": [
    ],
  • "portBindings": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get detailed container information

Authorizations:
bearerAuth
path Parameters
id
required
string

Container ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get container logs

Authorizations:
bearerAuth
path Parameters
id
required
string

Container ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List images

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get detailed image information

Authorizations:
bearerAuth
path Parameters
id
required
string

Image ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Remove a container image

Remove a container image from the local storage using CRI runtime (containerd, CRI-O)

Authorizations:
bearerAuth
path Parameters
id
required
string

Image ID or reference

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Import container image from tarball

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
image
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create resumable upload session

Alternative path for creating resumable upload session for container images using TUS protocol.
Authorizations:
bearerAuth
header Parameters
Upload-Length
required
integer <int64>

Total size of the file to upload

Upload-Metadata
string

Metadata about the upload (filename, etc.)

Responses

Response samples

Content type
application/json
{
  • "upload_id": "abc123-def456-ghi789",
  • "upload_url": "/containers/images/upload/abc123-def456-ghi789",
  • "expires_at": "2025-08-06T15:38:32Z"
}

List active upload sessions

This endpoint lists all active TUS upload sessions for container images, allowing you to:

  • Monitor multiple concurrent uploads
  • Resume interrupted uploads
  • Clean up stale upload sessions

Upload sessions expire after 24 hours of inactivity.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get upload session info

Get information about a resumable upload session for container images

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Upload chunk

Upload a chunk of data to a resumable upload session for container images

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

header Parameters
Upload-Offset
required
integer

Current upload offset

Content-Type
required
string
Value: "application/offset+octet-stream"

Must be application/offset+octet-stream

Request Body schema: application/offset+octet-stream
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get upload status

Get detailed status of a resumable upload session for container images

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Cancel upload session

Cancel and delete a resumable upload session for container images

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Complete upload and import image

Complete the upload session and import the container image

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Containers

Pull container image

Pull a container image from a registry using CRI runtime (containerd, CRI-O)

Authorizations:
bearerAuth
Request Body schema: application/json
required
image
required
string

Image reference (e.g., nginx:latest, docker.io/library/alpine:3.18)

Responses

Request samples

Content type
application/json
Example
{
  • "image": "nginx:latest"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Docker

Import Docker image from tarball

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
image
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create resumable upload session

Create a new resumable upload session for Docker image using TUS protocol

Authorizations:
bearerAuth
header Parameters
Upload-Length
required
integer <int64>

Total size of the file to upload

Upload-Metadata
string

Metadata about the upload (filename, etc.)

Responses

Response samples

Content type
application/json
{
  • "upload_id": "abc123-def456-ghi789",
  • "upload_url": "/docker/images/upload/abc123-def456-ghi789",
  • "expires_at": "2025-08-06T15:38:32Z"
}

List active upload sessions

List all active resumable upload sessions

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get upload session info

Get information about a resumable upload session

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Upload chunk

Upload a chunk of data to a resumable upload session

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

header Parameters
Upload-Offset
required
integer <int64>

Byte offset where this chunk starts

Content-Type
required
string
Value: "application/offset+octet-stream"

Must be application/offset+octet-stream

Request Body schema: application/offset+octet-stream
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get upload status

Get detailed status of a resumable upload session

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Cancel upload session

Cancel a resumable upload session

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Complete upload and import image

Complete a resumable upload session and import the Docker image

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List Docker containers

List Docker containers with optional filtering and pagination. Returns information about container state, image, ports, and resource usage.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List Docker images

List all Docker images available on the system

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Pull Docker image

Pull a Docker image from a registry (e.g., Docker Hub)

Authorizations:
bearerAuth
Request Body schema: application/json
required
imageName
string

Name of the image to pull

tag
string

Tag of the image to pull

Responses

Request samples

Content type
application/json
Example
{
  • "imageName": "nginx",
  • "tag": "latest"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create Docker container

Create a new Docker container from an image

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
string

Optional container name

image
string

Docker image to use for the container

cmd
Array of strings

Command to run in the container

entrypoint
Array of strings

Override the image entrypoint

env
Array of strings

List of environment variables to set in the container

object

Ports to expose from the container

object

Port mappings for exposed container ports

object

Metadata labels assigned to the container

workingDir
string

Working directory in the container

Array of objects
networkMode
string

Which network to connect container to

cgroupParent
string

Optional cgroup parent for the CRI sandbox (cgroupfs style, e.g., /system.slice).

object

Resource limits for the container

object

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my-nginx",
  • "image": "nginx:latest",
  • "env": [
    ],
  • "portBindings": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Remove Docker image

Remove a Docker image from the system

Authorizations:
bearerAuth
path Parameters
id
required
string

Image ID or tag

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List Docker networks

List all Docker networks configured on the system

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create Docker network

Create a new Docker network

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Name of the network to create

driver
string
Enum: "bridge" "host" "overlay" "macvlan" "none"

Network driver to use (defaults to 'bridge')

subnet
string

Subnet in CIDR notation for custom IP allocation

gateway
string

Gateway IP address for the subnet

object

Key-value labels to attach to the network

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my-network",
  • "driver": "bridge"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Remove Docker network

Remove a Docker network from the system

Authorizations:
bearerAuth
path Parameters
id
required
string

Network ID or name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List Docker volumes

List all Docker volumes available on the system

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create Docker volume

Create a new Docker volume

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Name of the volume to create

driver
string

Volume driver to use (defaults to 'local')

object

Key-value labels to attach to the volume

Responses

Request samples

Content type
application/json
{
  • "name": "my-data-volume",
  • "driver": "local",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Remove Docker volume

Remove a Docker volume from the system

Authorizations:
bearerAuth
path Parameters
id
required
string

Volume name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get Docker container details

Get detailed information about a specific Docker container

Authorizations:
bearerAuth
path Parameters
id
required
string

Container ID or name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": { }
}

Remove Docker container

Remove a Docker container (must be stopped first)

Authorizations:
bearerAuth
path Parameters
id
required
string

Container ID or name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Start Docker container

Start a stopped Docker container

Authorizations:
bearerAuth
path Parameters
id
required
string

Container ID or name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Stop Docker container

Stop a running Docker container

Authorizations:
bearerAuth
path Parameters
id
required
string

Container ID or name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Kill Docker container

Forcefully kill a running Docker container using SIGKILL

Authorizations:
bearerAuth
path Parameters
id
required
string

Container ID or name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get Docker container logs

Get logs from a Docker container

Authorizations:
bearerAuth
path Parameters
id
required
string

Container ID or name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Virtualization Storage

List all storage pools

Returns a list of storage pools with optional filtering and pagination.

Filtering:

  • state: Filter by pool state (active, inactive, all)
  • type: Filter by pool type (dir, logical, disk, netfs, etc.)

Pagination:

  • page: Page number (default: 1)
  • page_size: Number of items per page (default: 50, max: 100)
Authorizations:
bearerAuth
query Parameters
state
string
Default: "all"
Enum: "all" "active" "inactive"
Example: state=active

Filter by pool state

type
string
Enum: "dir" "logical" "disk" "netfs" "iscsi" "scsi" "mpath" "rbd" "gluster" "zfs" "fs"
Example: type=dir

Filter by pool type

page
integer >= 1
Default: 1

Page number for pagination

page_size
integer [ 1 .. 100 ]
Default: 50

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create a new storage pool

Creates a new storage pool for directory, NFS, logical volume, or block-device-backed filesystem sources.

Directory pools (type: "dir"):

  • path is required and must be an absolute directory path.

Network filesystem pools (type: "netfs"):

  • source is required and should be an NFS source such as host:/export/path.
  • target is required and must be an absolute mount path.

Logical pools (type: "logical"):

  • source is required and should contain the source volume group name.
  • target defaults to /dev/<volume-group> when omitted.

Filesystem pools (type: "fs"):

  • source_device must be an available whole block device such as a local disk or multipath device.
  • filesystem is required and must be one of ext4, xfs, or ocfs2.
  • target is required and must be an absolute mount path.
  • When initialize_filesystem is enabled, libvirt will build the pool and initialize the selected device before mounting it.
  • overwrite may be set together with initialize_filesystem to allow reinitializing an existing filesystem.
  • For OCFS2 with ocfs2_heartbeat_mode: "global", provide dedicated heartbeat regions in ocfs2_heartbeat_regions (UUIDs or device paths).
Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Storage pool name.

type
required
string
Enum: "dir" "netfs" "logical" "fs"

Storage pool type.

path
string

Absolute path for directory-backed pools.

source
string

NFS source (host:/export/path) or logical pool source volume group name.

target
string

Target mount point or target path for the pool.

autostart
boolean

Whether the pool should start automatically on boot.

username
string

Optional username for authenticated network-backed pools.

password
string

Optional password for authenticated network-backed pools.

source_device
string

Absolute block device path for filesystem-backed pools.

filesystem
string
Enum: "ext4" "xfs" "ocfs2"

Filesystem type for filesystem-backed pools.

initialize_filesystem
boolean

Build or initialize the selected block device before starting a filesystem-backed pool.

overwrite
boolean

Allow overwriting an existing filesystem when initialize_filesystem is enabled.

ocfs2_heartbeat_mode
string

Indicates whether the heartbeat should be global or local

ocfs2_node_slots
integer

Total number of allocated node slots for an OCFS2 cluster

ocfs2_local_node_ip
string

IP Address assigned to this node for cluster communications

ocfs2_peer_node_ips
Array of strings

Array of IP Addresses for remote cluster nodes

ocfs2_heartbeat_regions
Array of strings

Dedicated OCFS2 heartbeat regions (UUIDs or device paths). Required when ocfs2_heartbeat_mode is global.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "vm-storage",
  • "type": "dir",
  • "path": "/var/lib/libvirt/images/vm-storage",
  • "autostart": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get storage pool details

Authorizations:
bearerAuth
path Parameters
name
required
string

Storage pool name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete a storage pool

Deletes a storage pool with validation to prevent accidental data loss.

Safety Features:

  • Pool with existing volumes cannot be deleted without explicit delete_volumes=true
  • Returns 409 Conflict if pool contains volumes and delete_volumes is false or not set
  • Error message includes volume count to inform the user

Deletion Process:

  1. Check for existing volumes in the pool
  2. If volumes exist and delete_volumes=false: reject with error
  3. Stop the pool if it's active
  4. Delete volumes if delete_volumes=true
  5. Undefine the pool

⚠️ Warning: Setting delete_volumes=true will permanently delete all volumes in the pool!

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: old-storage-pool

Storage pool name

query Parameters
delete_volumes
boolean
Default: false

Whether to delete all volumes in the pool.

  • false (default): Reject deletion if pool contains volumes
  • true: Delete all volumes along with the pool (DANGEROUS)

Responses

Response samples

Content type
application/json
{
  • "status": "error",
  • "error": {
    }
}

Update storage pool configuration

Updates the configuration of an existing storage pool. Currently supports updating autostart settings.

Authorizations:
bearerAuth
path Parameters
name
required
string

Storage pool name

Request Body schema: application/json
required
autostart
boolean

Enable or disable autostart for the pool

Responses

Request samples

Content type
application/json
Example
{
  • "autostart": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List all storage volumes

Retrieves a list of all storage volumes across all storage pools in the libvirt environment. This provides a consolidated view of all volumes regardless of which pool they belong to.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Virtualization Volume

List all volumes in a storage pool

Authorizations:
bearerAuth
path Parameters
pool_name
required
string

Storage pool name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create a new volume in a storage pool

Creates a new storage volume within the specified storage pool.

Validation rules:

  • name must be unique within the pool and use only letters, digits, hyphen (-) and underscore (_)
  • capacity is required and must be at least 1 MiB (1,048,576 bytes)
  • format, if provided, must be one of: qcow2, raw, vmdk, qed, vdi

If the pool does not have enough free space, the request will fail with a validation error.

Authorizations:
bearerAuth
path Parameters
pool_name
required
string

Storage pool name

Request Body schema: application/json
required
name
required
string

Name of the volume to create

driver
string

Volume driver to use (defaults to 'local')

object

Key-value labels to attach to the volume

Responses

Request samples

Content type
application/json
{
  • "name": "my-data-volume",
  • "driver": "local",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get storage volume details

Authorizations:
bearerAuth
path Parameters
pool_name
required
string

Storage pool name

vol_name
required
string

Storage volume name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete a storage volume

Deletes a storage volume from the specified storage pool.

By default, the API will prevent deletion of volumes that are still in use by one or more virtual machines. To force deletion of an in-use volume, set the force query parameter to true.

Authorizations:
bearerAuth
path Parameters
pool_name
required
string

Storage pool name

vol_name
required
string

Storage volume name

query Parameters
force
boolean
Default: false

When set to true, forces deletion of the volume even if it is currently attached to one or more virtual machines.

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Virtualization ISO

Create ISO upload session (TUS)

Create a new resumable upload session for ISO images using TUS protocol.

This endpoint follows TUS protocol v1.0.0 for resumable uploads.

Required headers:

  • Upload-Length: Total size of the ISO file in bytes
  • Upload-Metadata: Base64-encoded metadata (filename, os_type, os_variant, architecture, description, tags, pool_name). If pool_name is omitted, the ISO will be associated with the "default" pool.

Example Upload-Metadata header:

Upload-Metadata: filename dWJ1bnR1LTIyLjA0LWRlc2t0b3AtYW1kNjQuaXNv,os_type bGludXg=,os_variant dWJ1bnR1MjIuMDQ=
Authorizations:
bearerAuth
header Parameters
Upload-Length
required
integer

Total size of the ISO file in bytes

Upload-Metadata
string

Base64-encoded metadata about the ISO

Tus-Resumable
string
Default: 1.0.0

TUS protocol version (1.0.0)

Responses

Response samples

Content type
application/json
{
  • "upload_id": "string",
  • "upload_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    }
}

List active ISO upload sessions

Get a list of all active ISO upload sessions for the current user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "uploads": [
    ],
  • "count": 0
}

Get upload session info (TUS)

Get information about a resumable upload session for ISO images. This follows TUS protocol for HEAD requests.

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Upload ISO chunk (TUS)

Upload a chunk of data for an ISO file using TUS protocol.

Required headers:

  • Upload-Offset: Current offset in bytes
  • Content-Type: Must be "application/offset+octet-stream"

The request body should contain the raw binary data of the chunk.

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

header Parameters
Upload-Offset
required
integer

Current offset in bytes

Content-Type
required
string
Value: "application/offset+octet-stream"

Must be application/offset+octet-stream

Tus-Resumable
string
Default: 1.0.0

TUS protocol version

Request Body schema: application/offset+octet-stream
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get ISO upload status

Get detailed status of an ISO upload session

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Response samples

Content type
application/json
{
  • "upload_id": "string",
  • "status": "created",
  • "total_size": 0,
  • "uploaded_size": 0,
  • "progress": "75.25%",
  • "metadata": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Cancel ISO upload session

Cancel and delete an ISO upload session, removing any uploaded data

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Response samples

Content type
application/json
{
  • "message": "Upload cancelled successfully",
  • "upload_id": "string"
}

Complete ISO upload and register

Complete the upload session and register the ISO in the system. This will move the ISO to the final storage location and make it available for VM creation.

Authorizations:
bearerAuth
path Parameters
id
required
string

Upload session ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List available ISO images

List all available ISO images from the system.

Sources:

  • Database-managed ISOs
  • ISOs in /var/lib/libvirt/images/iso
  • ISOs in /var/lib/vapor/iso
  • ISOs in /usr/share/iso
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Upload ISO image

Upload (non resumable) a new ISO image to the system.

Options:

  • Direct file upload
  • Download from URL
  • Copy from existing path
Authorizations:
bearerAuth
Request Body schema:
required
file
string <binary>

ISO file to upload

name
string

Name for the ISO

description
string

Description of the ISO

pool_name
string

Optional associated storage pool name. Defaults to "default" when omitted.

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete ISO image

Delete an ISO image from the system

Authorizations:
bearerAuth
path Parameters
id
required
string

ISO ID or filename

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Virtualization Network

List all virtual networks

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create a new virtual network

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Name of the network to create

driver
string
Enum: "bridge" "host" "overlay" "macvlan" "none"

Network driver to use (defaults to 'bridge')

subnet
string

Subnet in CIDR notation for custom IP allocation

gateway
string

Gateway IP address for the subnet

object

Key-value labels to attach to the network

Responses

Request samples

Content type
application/json
{
  • "name": "my-network",
  • "driver": "bridge",
  • "subnet": "172.20.0.0/16",
  • "gateway": "172.20.0.1",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get virtual network details

Authorizations:
bearerAuth
path Parameters
name
required
string

Network name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update a virtual network

Update an existing virtual network configuration. The network will be stopped if active, updated, and restarted.

Authorizations:
bearerAuth
path Parameters
name
required
string

Network name

Request Body schema: application/json
required
mode
string
Enum: "nat" "route" "bridge" "private"

Network forwarding mode

bridge
string

Bridge name for the network

object (IPRange)

IP range configuration for network

object (DHCPConfig)

DHCP configuration for network

autostart
boolean

Whether to enable autostart for the network

Responses

Request samples

Content type
application/json
{
  • "mode": "nat",
  • "bridge": "string",
  • "ip_range": {
    },
  • "dhcp": {
    },
  • "autostart": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete a virtual network

Authorizations:
bearerAuth
path Parameters
name
required
string

Network name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get DHCP leases for a network

Retrieve active DHCP leases for a virtual network

Authorizations:
bearerAuth
path Parameters
name
required
string

Network name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get network ports

Retrieve list of ports (VM interfaces) attached to a virtual network

Authorizations:
bearerAuth
path Parameters
name
required
string

Network name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List network portgroups

Retrieve list of portgroups for a virtual network

Authorizations:
bearerAuth
path Parameters
name
required
string

Network name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create network portgroup

Add a new portgroup to a virtual network

Authorizations:
bearerAuth
path Parameters
name
required
string

Network name

Request Body schema: application/json
required
name
required
string

Name of the portgroup

default
boolean
Default: false

Whether this portgroup should be the default

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "default": false
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update network portgroup

Update an existing portgroup in a virtual network

Authorizations:
bearerAuth
path Parameters
name
required
string

Network name

portgroup-name
required
string

Portgroup name

Request Body schema: application/json
required
name
required
string

Name of the portgroup

default
boolean
Default: false

Whether this portgroup should be the default

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "default": false
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete network portgroup

Remove a portgroup from a virtual network

Authorizations:
bearerAuth
path Parameters
name
required
string

Network name

portgroup-name
required
string

Portgroup name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Start virtual network

Starts (activates) an existing virtual network.

Authorizations:
bearerAuth
path Parameters
name
required
string

Network name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Stop virtual network

Stops (deactivates) an existing virtual network.

Authorizations:
bearerAuth
path Parameters
name
required
string

Network name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Storage Adapters

List Storage Adapters

Returns a unified list of all host storage adapters, including both physical HBAs (FC/SAS/NVMe PCIe) discovered from hardware and software adapters (iSCSI, future NVMe/TCP) from managed configuration. This is the primary inventory source for the frontend adapter table.

Authorizations:
bearerAuth
query Parameters
class
string
Enum: "physical" "software"

Filter by adapter class

protocol
string
Enum: "fc" "sas" "iscsi" "nvme_tcp" "pcie_nvme" "nvme_rdma" "scsi"

Filter by adapter protocol

status
string

Filter by adapter status

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List disks attached to a storage adapter

Returns block devices currently mapped to the selected physical storage adapter.

Authorizations:
bearerAuth
path Parameters
adapter_id
required
string

Inventory adapter identifier

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Rescan Storage Adapters

Triggers a host-level adapter inventory refresh (SCSI host rescan, re-enumeration of all providers) and returns a summary of discovered adapters.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Storage - iSCSI

List deprecated iSCSI storage ports Deprecated

This endpoint is deprecated and always returns 410 Gone. Use /api/v1/network/interfaces and the main /api/v1/network/* APIs instead.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Create deprecated iSCSI storage port Deprecated

This endpoint is deprecated and always returns 410 Gone. Use /api/v1/network/* to provision dedicated interfaces instead.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Human-readable port name

fabric_type
required
string
Value: "linux_bridge"

Network fabric type

bridge
required
string

Bridge interface name

uplink_interface
required
string

Physical NIC uplink

vlan_id
integer or null

Optional VLAN tag

ip
required
string

IP address for iSCSI traffic

prefix
required
integer

Network prefix length

gateway
string

Optional gateway address

mtu
required
integer [ 1280 .. 9000 ]

Maximum transmission unit

dedicated_for
required
string
Value: "iscsi"

Port dedication purpose

Responses

Request samples

Content type
application/json
{
  • "name": "vmk-iscsi-01",
  • "fabric_type": "linux_bridge",
  • "bridge": "br-storage",
  • "uplink_interface": "eth1",
  • "vlan_id": 100,
  • "ip": "10.0.10.1",
  • "prefix": 24,
  • "gateway": "10.0.10.254",
  • "mtu": 9000,
  • "dedicated_for": "iscsi"
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Get deprecated iSCSI storage port Deprecated

This endpoint is deprecated and always returns 410 Gone. Use /api/v1/network/interfaces instead.

Authorizations:
bearerAuth
path Parameters
port_id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Update deprecated iSCSI storage port Deprecated

This endpoint is deprecated and always returns 410 Gone. Use /api/v1/network/* to update the underlying interface instead.

Authorizations:
bearerAuth
path Parameters
port_id
required
string
Request Body schema: application/json
required
name
string
ip
string
prefix
integer
gateway
string
mtu
integer [ 1280 .. 9000 ]
vlan_id
integer or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "ip": "string",
  • "prefix": 0,
  • "gateway": "string",
  • "mtu": 1280,
  • "vlan_id": 0
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Delete deprecated iSCSI storage port Deprecated

This endpoint is deprecated and always returns 410 Gone. Use /api/v1/network/* to manage the underlying interface instead.

Authorizations:
bearerAuth
path Parameters
port_id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get software iSCSI adapter

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Create software iSCSI adapter

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
string [ 1 .. 64 ] characters ^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62}[A-Za-z0-9...

Human-readable adapter name. If omitted or blank, the server generates iscsi-adapter-01.

initiator_iqn
string^iqn\.(\d{4})-(0[1-9]|1[0-2])\.[A-Za-z0-9](?:...

iSCSI Qualified Name for the initiator. If omitted or blank, the server generates iqn...mid-:, falling back to hostname-only or local.vapor when identity data is unavailable.

mode
string
Default: "single_path"
Enum: "single_path" "multipath"

Path mode for the adapter

node_startup
string
Default: "automatic"
Enum: "manual" "automatic"

Startup policy for sessions

Responses

Request samples

Content type
application/json
{
  • "name": "iscsi-adapter-01",
  • "initiator_iqn": "iqn.2026-03.node-01.example.local.mid-8de27706:iscsi-adapter-01",
  • "mode": "single_path",
  • "node_startup": "automatic"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Update software iSCSI adapter

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
string [ 1 .. 64 ] characters ^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62}[A-Za-z0-9...
mode
string
Enum: "single_path" "multipath"
node_startup
string
Enum: "manual" "automatic"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "mode": "single_path",
  • "node_startup": "manual"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Delete software iSCSI adapter

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

List interface bindings for software iSCSI adapter

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Bind interface to software iSCSI adapter

Binds an existing host network interface to the software iSCSI adapter. Use /api/v1/network/interfaces to discover eligible interface names and the main /api/v1/network/* APIs to create bridges, VLANs, or bonds before binding them here. Single-path adapters support at most one binding. Multipath adapters require at least two bindings for login workflows.

Authorizations:
bearerAuth
Request Body schema: application/json
required
interface_name
required
string

Existing host network interface name to bind to the adapter

port_id
string
Deprecated

Deprecated legacy compatibility field

Responses

Request samples

Content type
application/json
{
  • "interface_name": "string",
  • "port_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Remove software iSCSI port binding

Authorizations:
bearerAuth
path Parameters
binding_id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Discover iSCSI targets

Authorizations:
bearerAuth
Request Body schema: application/json
required
portal
string

Fallback target portal address (IP:port) used for paths without an explicit binding_portals override

Array of objects (ISCSIBindingPortalRequest)

Optional per-binding portal overrides for multipath discovery

Responses

Request samples

Content type
application/json
{
  • "portal": "172.16.1.2:3260",
  • "binding_portals": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

List discovered targets

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Forget iSCSI target configuration

Authorizations:
bearerAuth
Request Body schema: application/json
required
target_iqn
required
string

Target IQN whose open-iscsi node record should be removed

portal
required
string

Target portal address (IP:port) for the node record to remove

Responses

Request samples

Content type
application/json
{
  • "target_iqn": "iqn.2022-04.world.srv:dlp.target01",
  • "portal": "127.0.0.1:3260"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

List active iSCSI sessions

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Login to iSCSI target

Authorizations:
bearerAuth
Request Body schema: application/json
required
target_iqn
required
string

Target IQN to login to

portal
string

Fallback target portal address (IP:port) used for paths without an explicit binding_portals override

Array of objects (ISCSIBindingPortalRequest)

Optional per-binding portal overrides for multipath login

username
string

Optional CHAP username; provide together with password

password
string

Optional CHAP password (write-only); provide together with username

Responses

Request samples

Content type
application/json
{
  • "target_iqn": "iqn.2020-01.com.example:storage.lun1",
  • "portal": "172.16.1.2:3260",
  • "binding_portals": [
    ],
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": { }
}

Logout from iSCSI session

Authorizations:
bearerAuth
path Parameters
session_id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Rescan software iSCSI sessions

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

List LUNs visible through software iSCSI adapter

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

List logical devices managed through software iSCSI adapter

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Storage - Multipath

List multipath devices

Returns all multipath devices with path details and health status

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get multipath device by WWID

Authorizations:
bearerAuth
path Parameters
wwid
required
string

World Wide Identifier of the multipath device

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

List paths for multipath device

Authorizations:
bearerAuth
path Parameters
wwid
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Update multipath device policy

Change the path selection policy for a multipath device

Authorizations:
bearerAuth
path Parameters
wwid
required
string
Request Body schema: application/json
required
policy
required
string
Enum: "round_robin" "failover"

Path selection policy

Responses

Request samples

Content type
application/json
{
  • "policy": "round_robin"
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Rescan multipath devices

Triggers a full rescan of all multipath devices and paths

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get multipathd daemon status

Returns the running state of the multipathd daemon including device and path statistics

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Get multipath defaults configuration

Returns the current defaults section from the running multipathd configuration

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Update multipath defaults configuration

Applies a partial update to multipath defaults via a drop-in config file and reconfigures the daemon

Authorizations:
bearerAuth
Request Body schema: application/json
required
polling_interval
integer
path_grouping_policy
string
path_selector
string
path_checker
string
features
string
no_path_retry
string
rr_min_io
integer
rr_min_io_rq
integer
user_friendly_names
string
find_multipaths
string
flush_on_last_del
string
max_fds
integer
verbosity
integer

Responses

Request samples

Content type
application/json
{
  • "polling_interval": 0,
  • "path_grouping_policy": "string",
  • "path_selector": "string",
  • "path_checker": "string",
  • "features": "string",
  • "no_path_retry": "string",
  • "rr_min_io": 0,
  • "rr_min_io_rq": 0,
  • "user_friendly_names": "string",
  • "find_multipaths": "string",
  • "flush_on_last_del": "string",
  • "max_fds": 0,
  • "verbosity": 0
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get multipath blacklist configuration

Returns the blacklist and blacklist_exceptions sections from the running multipathd configuration

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Update multipath blacklist configuration

Replaces the blacklist and blacklist_exceptions via a drop-in config file and reconfigures the daemon

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object (MultipathBlacklistSection)
required
object (MultipathBlacklistSection)

Responses

Request samples

Content type
application/json
{
  • "blacklist": {
    },
  • "exceptions": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get multipath topology

Returns the full topology tree of multipath maps, path groups, and paths

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Storage - OCFS2 (o2cb)

List OCFS2 clusters

Returns all OCFS2 clusters registered via o2cb

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Create an OCFS2 cluster

Creates a new OCFS2 cluster via o2cb. The cluster name must contain only alpha-numeric characters.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Cluster name (alpha-numeric characters only)

Responses

Request samples

Content type
application/json
{
  • "name": "vapor"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Get OCFS2 cluster details

Returns detailed information about a specific OCFS2 cluster, including nodes and heartbeat regions.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Remove an OCFS2 cluster

Removes an OCFS2 cluster and its configuration from o2cb.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get OCFS2 cluster status

Returns the online/offline status of an OCFS2 cluster.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

List nodes in an OCFS2 cluster

Returns all nodes registered in the specified OCFS2 cluster.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Add a node to an OCFS2 cluster

Adds a new node to the specified OCFS2 cluster. The node port defaults to 7777 if not specified.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Request Body schema: application/json
required
name
required
string

Node name

ip
required
string

IP address of the node

port
integer

Port the node listens on (defaults to 7777)

number
integer

Optional explicit node number assignment

Responses

Request samples

Content type
application/json
{
  • "name": "node1",
  • "ip": "192.168.1.10",
  • "port": 7777,
  • "number": 0
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Remove a node from an OCFS2 cluster

Removes a node from the specified OCFS2 cluster.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

node
required
string

Node name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

List heartbeat regions in an OCFS2 cluster

Returns all heartbeat regions registered for the specified OCFS2 cluster.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Add a heartbeat region to an OCFS2 cluster

Adds a heartbeat region for a block device to the specified OCFS2 cluster.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Request Body schema: application/json
required
device
required
string

Block device path for the heartbeat region

Responses

Request samples

Content type
application/json
{
  • "device": "/dev/mapper/mpathb"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Remove a heartbeat region from an OCFS2 cluster

Removes a heartbeat region from the specified OCFS2 cluster.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Request Body schema: application/json
required
device
required
string

Block device path for the heartbeat region

Responses

Request samples

Content type
application/json
{
  • "device": "/dev/mapper/mpathb"
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Set heartbeat mode for an OCFS2 cluster

Sets the heartbeat mode (global or local) for the specified OCFS2 cluster.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Request Body schema: application/json
required
mode
required
string
Enum: "global" "local"

Heartbeat mode for the cluster

Responses

Request samples

Content type
application/json
{
  • "mode": "global"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Register an OCFS2 cluster with configfs

Registers the specified OCFS2 cluster with the kernel configfs interface, making it active.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Unregister an OCFS2 cluster from configfs

Unregisters the specified OCFS2 cluster from the kernel configfs interface.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Start global heartbeat for an OCFS2 cluster

Starts the global heartbeat mechanism for the specified OCFS2 cluster.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Stop global heartbeat for an OCFS2 cluster

Stops the global heartbeat mechanism for the specified OCFS2 cluster.

Authorizations:
bearerAuth
path Parameters
cluster
required
string

Cluster name

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Users

List users

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create user

Authorizations:
bearerAuth
Request Body schema: application/json
required
username
required
string
password
string
groups
string

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string",
  • "groups": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update user

Authorizations:
bearerAuth
path Parameters
username
required
string
Request Body schema: application/json
required
username
required
string
password
string
groups
string

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string",
  • "groups": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete user

Authorizations:
bearerAuth
path Parameters
username
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Reset user password

Authorizations:
bearerAuth
path Parameters
username
required
string

The username of the user whose password to reset

Request Body schema: application/json
required
password
required
string >= 6 characters

New password for the user (minimum 6 characters)

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Logs

Query system logs

Authorizations:
bearerAuth
query Parameters
service
string

Filter by service name

priority
string
Enum: "emergency" "alert" "critical" "error" "warning" "notice" "info" "debug"

Filter by priority

since
string

Show logs since timestamp

until
string

Show logs until timestamp

page
integer
Default: 1
page_size
integer <= 1000
Default: 100

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

System

Get system summary

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get hardware information

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get firmware information

Returns firmware details for the system (BIOS, BMC/IPMI), storage adapters (SCSI hosts and NVMe controllers), and physical network adapters. Driver versions are resolved via modinfo; NIC firmware is read via ethtool.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get memory information

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get CPU information

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Upload new TLS certificates

Request Body schema: multipart/form-data
required
cert
string <binary>

The certificate file (PEM format)

key
string <binary>

The private key file (PEM format)

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Regenerate self-signed TLS certificates

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Download the server's public certificate

Responses

Get chrony time synchronization status

Returns combined tracking information, NTP sources, and parsed configuration

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List NTP sources

Returns the current NTP source list from chronyc

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Add NTP source

Add a new server or pool entry to chrony.conf and reload

Authorizations:
bearerAuth
Request Body schema: application/json
required
type
required
string
Enum: "server" "pool"

Whether to add as a server or pool

address
required
string

NTP server hostname or IP address

iburst
boolean
Default: false

Enable iburst for faster initial sync

maxSources
integer [ 1 .. 16 ]

Maximum sources for pool type

Responses

Request samples

Content type
application/json
{
  • "type": "server",
  • "address": "time.google.com",
  • "iburst": false,
  • "maxSources": 4
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Remove NTP source

Remove a server or pool entry from chrony.conf and reload

Authorizations:
bearerAuth
path Parameters
address
required
string
Example: time.google.com

NTP server hostname or IP address to remove

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update chrony configuration

Update chrony configuration options such as makestep, rtcsync, maxupdateskew, and logdir

Authorizations:
bearerAuth
Request Body schema: application/json
required
makestep
string

Makestep threshold and limit (e.g. '1 3')

rtcsync
boolean

Enable or disable kernel RTC synchronization

maxupdateskew
string

Maximum allowed skew in ppm

logdir
string

Chrony log directory path

Responses

Request samples

Content type
application/json
{
  • "makestep": "1 3",
  • "rtcsync": true,
  • "maxupdateskew": "100.0",
  • "logdir": "/var/log/chrony"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Force time step

Execute chronyc makestep to force an immediate clock adjustment

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

System Events WebSocket

Establish a WebSocket connection to receive event channels (metrics, logs, VM/storage/network events, and durable sync-events). To subscribe: 1. Send {"type":"auth","payload":{"token":"<jwt>"}} 2. Send {"type":"subscribe","payload":{"channel":"sync-events","resume_from":18442}} For sync-events, replay is ordered by seq and at-least-once. If host is not actively managed by Cockpit, subscribe returns an error with code=not_managed_by_cockpit. If resume_from is too old (pruned), server sends an error message with code=cursor_expired and oldest_available_seq; clients must re-fetch /api/v1/sync/snapshot and resume from snapshot_end_seq.

query Parameters
token
string

Authentication token

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Sync

Durable sync snapshot with watermark

Returns the current inventory snapshot used by Cockpit reconciliation and watermark cursors from a consistent-cut snapshot barrier. snapshot_start_seq and snapshot_end_seq are captured while event commits are blocked, so replaying /sync/events?after=snapshot_end_seq guarantees no missed mutations. watermark_seq is retained for backward compatibility and equals snapshot_end_seq.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "error": null
}

Replay durable sync events

Replays durable mutation events ordered by increasing global seq. The server returns only events where seq > after. Replay is at-least-once: clients should de-duplicate with (resource_type, resource_id, resource_version). For snapshots, use /sync/snapshot and replay with after=snapshot_end_seq (or watermark_seq for legacy clients).

Authorizations:
bearerAuth
query Parameters
after
integer <int64> >= 0
Default: 0

Replay cursor. Only events with seq > after are returned.

limit
integer [ 1 .. 1000 ]
Default: 200

Maximum events to return in this page.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "error": null
}

Control Plane

Claim or renew control-plane ownership lease

Claims active management ownership for this Vapor host on behalf of a Cockpit control plane. If the same owner re-claims while lease is active, the call is idempotent and renews heartbeat/lease timestamps. If a different owner holds an active lease, returns 409 owner_conflict.

Authorizations:
bearerAuth
Request Body schema: application/json
required
control_plane_id
required
string <uuid>

Cockpit cp_instance.id

site_name
required
string

Cockpit cp_instance.site_name

Responses

Request samples

Content type
application/json
{
  • "control_plane_id": "5869c439-9b48-401c-a9ef-46fffae045df",
  • "site_name": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "error": null
}

Release control-plane ownership lease

Releases active management ownership for the current control plane owner. If no claim currently exists, this operation is idempotent and returns success with an unmanaged/unclaimed status. If an active claim exists, only the current owner can release it; mismatched owners return 409 owner_conflict.

Authorizations:
bearerAuth
Request Body schema: application/json
required
control_plane_id
required
string <uuid>

Cockpit cp_instance.id

site_name
required
string

Cockpit cp_instance.site_name

Responses

Request samples

Content type
application/json
{
  • "control_plane_id": "5869c439-9b48-401c-a9ef-46fffae045df",
  • "site_name": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "error": null
}

Renew control-plane lease heartbeat

Renews last_heartbeat_at and lease_expires_at for the current active owner. If no claim exists or ownership mismatches, returns conflict.

Authorizations:
bearerAuth
Request Body schema: application/json
required
control_plane_id
required
string <uuid>

Cockpit cp_instance.id

site_name
required
string

Cockpit cp_instance.site_name

Responses

Request samples

Content type
application/json
{
  • "control_plane_id": "5869c439-9b48-401c-a9ef-46fffae045df",
  • "site_name": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "error": null
}

Get control-plane active management status

Returns current claim owner, heartbeat lease timestamps, managed status (managed, unmanaged, expired), and optional claim_start_seq.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "error": null
}

WebSocket

WebSocket endpoint for live system metrics

Establish a WebSocket connection to receive real-time system metrics.

WebSocket URL: ws://localhost:8080/ws/metrics

Authentication: Send JWT token in the first message after connection:

{
  "type": "auth",
  "payload": {
    "token": "your-jwt-token"
  }
}

Subscribe to metrics:

{
  "type": "subscribe"
}

Unsubscribe from metrics:

{
  "type": "unsubscribe"
}

Server messages will be in the format:

{
  "type": "metric",
  "metric": "cpu",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": { ... }
}
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

WebSocket endpoint for live system logs

Establish a WebSocket connection to receive real-time system logs.

WebSocket URL: ws://localhost:8080/ws/logs

Authentication: Send JWT token in the first message after connection:

{
  "type": "auth",
  "payload": {
    "token": "your-jwt-token"
  }
}

Subscribe Examples:

  1. All logs from all services (most verbose):
{
  "type": "subscribe",
  "payload": {
    "filters": {
      "follow": true
    }
  }
}
  1. Specific service logs:
{
  "type": "subscribe",
  "payload": {
    "filters": {
      "unit": "sshd",
      "priority": "info",
      "follow": true
    }
  }
}
  1. Kernel messages:
{
  "type": "subscribe",
  "payload": {
    "filters": {
      "unit": "kernel",
      "follow": true
    }
  }
}
  1. Recent logs (last 10 minutes):
{
  "type": "subscribe",
  "payload": {
    "filters": {
      "since": "10 minutes ago",
      "follow": true
    }
  }
}

Server Response Format:

{
  "type": "data",
  "payload": {
    "timestamp": "2024-01-15T10:30:00Z",
    "level": "info",
    "unit": "sshd.service",
    "message": "Accepted publickey for john from 192.168.1.100 port 52341 ssh2"
  }
}

Priority Levels (from least to most severe):

  • debug - Debugging messages
  • info - Informational messages
  • notice - Normal but significant messages
  • warning - Warning messages
  • error - Error messages
  • critical - Critical messages
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

WebSocket Terminal Connection

Establish a WebSocket connection for an interactive terminal session.

WebSocket URL: ws://localhost:8080/ws/terminal

Authentication: Send JWT token in the first message after connection:

{
  "type": "auth",
  "payload": {
    "token": "your-jwt-token"
  }
}

Start terminal session:

{
  "type": "subscribe",
  "payload": {
    "cols": 80,
    "rows": 24,
    "shell": "/bin/bash"
  }
}

Send input:

{
  "type": "input",
  "data": "ls -la\n"
}

Resize terminal:

{
  "type": "resize",
  "payload": {
    "cols": 120,
    "rows": 40
  }
}

Server messages will be in the format:

{
  "type": "output",
  "data": "terminal output..."
}
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Kubernetes Pod Exec WebSocket

Establish a WebSocket connection to execute commands in a Kubernetes pod

query Parameters
namespace
required
string
pod
required
string
container
string
token
string

Authentication token

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

System Events WebSocket

Establish a WebSocket connection to receive event channels (metrics, logs, VM/storage/network events, and durable sync-events). To subscribe: 1. Send {"type":"auth","payload":{"token":"<jwt>"}} 2. Send {"type":"subscribe","payload":{"channel":"sync-events","resume_from":18442}} For sync-events, replay is ordered by seq and at-least-once. If host is not actively managed by Cockpit, subscribe returns an error with code=not_managed_by_cockpit. If resume_from is too old (pruned), server sends an error message with code=cursor_expired and oldest_available_seq; clients must re-fetch /api/v1/sync/snapshot and resume from snapshot_end_seq.

query Parameters
token
string

Authentication token

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Virtualization

List OS variants

Returns OS variants from the libosinfo database by running osinfo-query os.

This endpoint is used by the frontend to provide suggestions for:

  • VM creation (os_variant)
  • ISO upload metadata (os_variant)
Authorizations:
bearerAuth
query Parameters
q
string

Case-insensitive substring filter applied to short_id, name, version, distro, vendor, id.

family
string

Filter by OS family (e.g. linux, windows).

limit
integer [ 0 .. 2000 ]

Maximum number of results to return.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get virtualization domain capabilities

Returns parsed libvirt domain capabilities (including machine types)

query Parameters
arch
string

Architecture to query (default derived from host)

virt_type
string

Virtualization type (kvm or qemu)

machine_type
string

Machine type to query for

emulator
string

Emulator binary path to use

include_raw
boolean

Include raw domain capabilities XML

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Kubernetes

Kubernetes Pod Exec WebSocket

Establish a WebSocket connection to execute commands in a Kubernetes pod

query Parameters
namespace
required
string
pod
required
string
container
string
token
string

Authentication token

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

List all Kubernetes Custom Resource Definitions

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a Custom Resource Definition

Create or update a Custom Resource Definition in the Kubernetes cluster using apply semantics. If the CRD doesn't exist, it will be created. If it exists, it will be updated.

Supports both JSON and YAML formats. If Content-Type is not specified, defaults to JSON.

Authorizations:
bearerAuth
Request Body schema:
required
object

Responses

Request samples

Content type
{
  • "apiVersion": "apiextensions.k8s.io/v1",
  • "kind": "CustomResourceDefinition",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Get detailed CRD information

Get detailed information about a specific Custom Resource Definition

Authorizations:
bearerAuth
path Parameters
name
required
string

CRD name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update a Custom Resource Definition

Update an existing Custom Resource Definition in the Kubernetes cluster.

Supports both JSON and YAML formats. If Content-Type is not specified, defaults to JSON.

Authorizations:
bearerAuth
path Parameters
name
required
string

CRD name

Request Body schema:
required
object

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Update a Custom Resource Definition

Update an existing Custom Resource Definition in the Kubernetes cluster.

Supports both JSON and YAML formats. If Content-Type is not specified, defaults to JSON.

Authorizations:
bearerAuth
path Parameters
name
required
string

CRD name

Request Body schema:
required
object

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

Delete a Custom Resource Definition

Delete an existing Custom Resource Definition from the Kubernetes cluster

Authorizations:
bearerAuth
path Parameters
name
required
string

CRD name

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "data": {
    }
}

List all objects for a specific CRD

List all custom resource instances for a specific CRD with complete object data. Returns full objects including metadata, spec, status, and all custom fields defined by the CRD.

Authorizations:
bearerAuth
path Parameters
name
required
string

CRD name

query Parameters
namespace
string

Namespace to filter objects by. If not provided, all namespaces are searched for cluster-scoped CRDs, and the default namespace is used for namespaced-scoped CRDs.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create a CRD object instance

Create a new instance of a Custom Resource Definition.

Supports both JSON and YAML request formats based on the Content-Type header:

  • application/json - JSON format
  • application/yaml, text/yaml - YAML format

The namespace can be specified either:

  • As a query parameter for namespaced CRDs
  • Omitted for cluster-scoped CRDs

The API will automatically set the appropriate apiVersion and kind if not provided.

Authorizations:
bearerAuth
path Parameters
name
required
string

CRD name (e.g., mycrds.example.com)

query Parameters
namespace
string

Namespace for the CRD instance. Required for namespaced CRDs, must be omitted for cluster-scoped CRDs.

Request Body schema:
required

CRD object specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "example.com/v1",
  • "kind": "MyCRD",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
{
  • "success": true,
  • "data": {
    }
}

Get CRD object instance

Get a specific instance of a Custom Resource Definition.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns CRD object wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
name
required
string

CRD name

namespace
required
string

Namespace

object-name
required
string

Object name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "data": {
    },
  • "error": {
    }
}

Update a CRD object instance

Update an existing instance of a Custom Resource Definition.

Supports both JSON and YAML request formats based on the Content-Type header:

  • application/json - JSON format
  • application/yaml, text/yaml - YAML format

For namespaced CRDs, the namespace must be specified in the path. For cluster-scoped CRDs, use "-" as the namespace parameter.

The object name in the path must match the metadata.name in the request body.

Authorizations:
bearerAuth
path Parameters
name
required
string

CRD name (e.g., mycrds.example.com)

namespace
required
string

Namespace of the CRD instance. Use "-" for cluster-scoped CRDs.

object-name
required
string

Name of the CRD object instance

Request Body schema:
required

Updated CRD object specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "example.com/v1",
  • "kind": "MyCRD",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
{
  • "success": true,
  • "data": {
    }
}

Patch a CRD object instance

Partially update an existing instance of a Custom Resource Definition.

This endpoint behaves identically to PUT for CRD objects, performing a full update. Both JSON and YAML formats are supported based on the Content-Type header.

For namespaced CRDs, the namespace must be specified in the path. For cluster-scoped CRDs, use "-" as the namespace parameter.

Authorizations:
bearerAuth
path Parameters
name
required
string

CRD name (e.g., mycrds.example.com)

namespace
required
string

Namespace of the CRD instance. Use "-" for cluster-scoped CRDs.

object-name
required
string

Name of the CRD object instance

Request Body schema:
required

Partial or full CRD object specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{ }

Response samples

Content type
{
  • "success": true,
  • "data": {
    }
}

Delete a CRD object instance

Delete an existing instance of a Custom Resource Definition.

For namespaced CRDs, the namespace must be specified in the path. For cluster-scoped CRDs, use "-" as the namespace parameter.

Authorizations:
bearerAuth
path Parameters
name
required
string

CRD name (e.g., mycrds.example.com)

namespace
required
string

Namespace of the CRD instance. Use "-" for cluster-scoped CRDs.

object-name
required
string

Name of the CRD object instance to delete

Responses

Response samples

Content type
{
  • "success": true,
  • "data": {
    }
}

List all pods in the cluster

List all pods across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a pod

Create a new pod or update an existing pod using Kubernetes apply semantics.

Supports both JSON and YAML content types:

  • For JSON: Set Content-Type to "application/json"
  • For YAML: Set Content-Type to "application/yaml" or "text/yaml"

If no Content-Type is specified, JSON is assumed by default.

Authorizations:
bearerAuth
Request Body schema:
required

Pod specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "v1",
  • "kind": "Pod",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "pod_detail": {
    },
  • "error": {
    }
}

List all deployments in the cluster

List all deployments across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a Deployment

Create a new Deployment or update an existing Deployment using Kubernetes apply semantics.

Authorizations:
bearerAuth
Request Body schema:
required

Deployment specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "apps/v1",
  • "kind": "Deployment",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

List all services in the cluster

List all services across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a Service

Create a new Service or update an existing Service using Kubernetes apply semantics.

Authorizations:
bearerAuth
Request Body schema:
required

Service specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "v1",
  • "kind": "Service",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

List all ingresses in the cluster

List all ingresses across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update an Ingress

Create a new Ingress or update an existing Ingress using Kubernetes apply semantics.

Authorizations:
bearerAuth
Request Body schema:
required

Ingress specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "networking.k8s.io/v1",
  • "kind": "Ingress",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

List all persistent volume claims in the cluster

List all PVCs across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a PVC

Create a new PVC or update an existing PVC using Kubernetes apply semantics.

Authorizations:
bearerAuth
Request Body schema:
required

PVC specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "v1",
  • "kind": "PersistentVolumeClaim",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

List all persistent volumes in the cluster

List all PVs in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a PV

Create a new PV or update an existing PV using Kubernetes apply semantics.

Authorizations:
bearerAuth
Request Body schema:
required

PV specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "v1",
  • "kind": "PersistentVolume",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

List all secrets in the cluster

List all secrets across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List all config maps in the cluster

List all config maps across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List all namespaces in the cluster

List all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a Namespace

Create a new Namespace or update an existing one using Kubernetes apply semantics.

Authorizations:
bearerAuth
Request Body schema:
required

Namespace specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "v1",
  • "kind": "Namespace",
  • "metadata": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

List all nodes in the cluster

List all nodes in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List all daemon sets in the cluster

List all daemon sets across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a daemon set

Create or update a daemon set in the Kubernetes cluster using apply semantics. If the daemon set doesn't exist, it will be created. If it exists, it will be updated.

Supports both JSON and YAML formats. If Content-Type is not specified, defaults to JSON.

Authorizations:
bearerAuth
Request Body schema:
required
property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "apps/v1",
  • "kind": "DaemonSet",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "daemonset_detail": {
    },
  • "error": {
    }
}

List all stateful sets in the cluster

List all stateful sets across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a stateful set

Create or update a stateful set in the Kubernetes cluster using apply semantics. If the stateful set doesn't exist, it will be created. If it exists, it will be updated.

Supports both JSON and YAML formats. If Content-Type is not specified, defaults to JSON.

Authorizations:
bearerAuth
Request Body schema:
required
property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "apps/v1",
  • "kind": "StatefulSet",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "statefulset_detail": {
    },
  • "error": {
    }
}

List all jobs in the cluster

List all jobs across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a job

Create or update a job in the Kubernetes cluster using apply semantics. If the job doesn't exist, it will be created. If it exists, it will be updated.

Supports both JSON and YAML formats. If Content-Type is not specified, defaults to JSON.

Authorizations:
bearerAuth
Request Body schema:
required
property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "batch/v1",
  • "kind": "Job",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "job_detail": {
    },
  • "error": {
    }
}

List all cron jobs in the cluster

List all cron jobs across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a cron job

Create or update a cron job in the Kubernetes cluster using apply semantics. If the cron job doesn't exist, it will be created. If it exists, it will be updated.

Supports both JSON and YAML formats. If Content-Type is not specified, defaults to JSON.

Authorizations:
bearerAuth
Request Body schema:
required
property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "batch/v1",
  • "kind": "CronJob",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "cronjob_detail": {
    },
  • "error": {
    }
}

Get cluster information

Get basic information about the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List all ingress classes in the cluster

List all ingress classes in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update an IngressClass

Create a new IngressClass or update an existing IngressClass using Kubernetes apply semantics.

Authorizations:
bearerAuth
Request Body schema:
required

IngressClass specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "networking.k8s.io/v1",
  • "kind": "IngressClass",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Get detailed IngressClass information

Get detailed information about a specific IngressClass.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns IngressClass wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
name
required
string

IngressClass name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "ingressclass_detail": {
    },
  • "error": {
    }
}

Update an IngressClass

Update an existing IngressClass

Authorizations:
bearerAuth
path Parameters
name
required
string

IngressClass name

Request Body schema:
required

IngressClass specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "networking.k8s.io/v1",
  • "kind": "IngressClass",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Delete an ingress class

Delete a specific ingress class

Authorizations:
bearerAuth
path Parameters
name
required
string

IngressClass name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List all network policies in the cluster

List all network policies across all namespaces in the Kubernetes cluster

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create or update a NetworkPolicy

Create a new NetworkPolicy or update an existing NetworkPolicy using Kubernetes apply semantics.

Authorizations:
bearerAuth
Request Body schema:
required

NetworkPolicy specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "networking.k8s.io/v1",
  • "kind": "NetworkPolicy",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Get detailed NetworkPolicy information

Get detailed information about a specific NetworkPolicy in a namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns NetworkPolicy wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
namespace
required
string

NetworkPolicy namespace

name
required
string

NetworkPolicy name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "networkpolicy_detail": {
    },
  • "error": {
    }
}

Update a NetworkPolicy

Update an existing NetworkPolicy

Authorizations:
bearerAuth
path Parameters
namespace
required
string

NetworkPolicy namespace

name
required
string

NetworkPolicy name

Request Body schema:
required

NetworkPolicy specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "networking.k8s.io/v1",
  • "kind": "NetworkPolicy",
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Delete a network policy

Delete a specific network policy from a namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

NetworkPolicy namespace

name
required
string

NetworkPolicy name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List pods in a specific namespace

List all pods in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list pods from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List deployments in a specific namespace

List all deployments in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list deployments from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List services in a specific namespace

List all services in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list services from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List ingresses in a specific namespace

List all ingresses in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list ingresses from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List persistent in a specific namespace

List all persistent in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list persistent from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List secrets in a specific namespace

List all secrets in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list secrets from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List config in a specific namespace

List all config in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list config from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List daemon in a specific namespace

List all daemon in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list daemon from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List stateful in a specific namespace

List all stateful in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list stateful from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List jobs in a specific namespace

List all jobs in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list jobs from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List cron in a specific namespace

List all cron in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list cron from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List network in a specific namespace

List all network in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list network from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List replica in a specific namespace

List all replica in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list replica from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List service in a specific namespace

List all service in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list service from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List roles in a specific namespace

List all roles in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list roles from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List role in a specific namespace

List all role in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list role from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List horizontal in a specific namespace

List all horizontal in the specified namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

The namespace to list horizontal from

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get detailed pod information

Get detailed information about a specific pod in a namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Pod namespace

name
required
string

Pod name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "pod_detail": {
    },
  • "error": {
    }
}

Update a Pod

Update an existing Pod

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Pod namespace

name
required
string

Pod name

Request Body schema:
required

Pod specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "v1",
  • "kind": "Pod",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Delete a pod

Delete a specific pod from a namespace

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Pod namespace

name
required
string

Pod name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "string"
}

Update container images in a Pod

Update one or more container images in a Pod specification.

Important limitations:

  • Pods are immutable: Once a Pod has started running, its container images cannot be changed
  • This endpoint only works for Pods in Pending state that haven't started yet
  • Managed Pods: If a Pod is managed by a controller (Deployment, StatefulSet, DaemonSet, etc.), this operation will be rejected. You should update the controller instead.
  • Manual Pods only: This is primarily useful for standalone Pods not managed by any controller

For running Pods, you must:

  1. Delete the existing Pod
  2. Create a new Pod with the updated images

This is equivalent to running:

kubectl set image pod/{name} container1=image1 container2=image2 -n {namespace}

Note: Unlike workload resources (Deployments, StatefulSets, DaemonSets), Pods do not support rollout operations like restart or undo since they are not managed by a controller and don't maintain revision history.

Authorizations:
bearerAuth
path Parameters
namespace
required
string
Example: default

Pod namespace

name
required
string
Example: standalone-pod

Pod name

Request Body schema: application/json
required

Array of container name to image mappings. Each object in the array should have a single key-value pair where:

  • Key: container name (must exist in the Pod's regular containers, not init containers)
  • Value: new image to use (including tag)

Note: This operation does not support updating init container images.

Array (non-empty)
property name*
additional property
string

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Successfully updated images for Pod default/standalone-pod",
  • "warning": "Pod image update was applied to the specification, but the Pod must be deleted and recreated for changes to take effect.",
  • "updated_images": {
    },
  • "pod": {
    }
}

Get pod logs

Retrieve logs from a specific pod

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Pod namespace

name
required
string

Pod name

query Parameters
follow
boolean
Default: false

Follow the log output

lines
integer
Default: 100

Number of lines to retrieve from the end of the logs

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "logs": "string"
}

Get detailed deployment information

Get detailed information about a specific deployment in a namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns deployment wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
namespace
required
string

Deployment namespace

name
required
string

Deployment name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "deployment_detail": {
    },
  • "error": {
    }
}

Update a Deployment

Update an existing Deployment

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Deployment namespace

name
required
string

Deployment name

Request Body schema:
required

Deployment specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "apps/v1",
  • "kind": "Deployment",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Delete a Deployment

Delete a specific Deployment

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Deployment namespace

name
required
string

Deployment name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Restart deployment pods

Trigger a rolling restart of all pods managed by a deployment.

This operation works by adding or updating a restart annotation (kubectl.kubernetes.io/restartedAt) on the deployment's pod template, which triggers Kubernetes to perform a rolling update with new pods.

This is equivalent to running:

kubectl rollout restart deployment/{name} -n {namespace}
Authorizations:
bearerAuth
path Parameters
namespace
required
string
Example: default

Deployment namespace

name
required
string
Example: nginx-deployment

Deployment name

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Deployment default/nginx-deployment has been restarted",
  • "deployment": {
    }
}

Rollback deployment to previous revision

Rollback a deployment to its previous revision.

This operation retrieves the previous revision from the deployment's ReplicaSets and updates the deployment to use the pod template from that previous revision. The rollback triggers a rolling update to replace current pods with pods from the previous configuration.

This is equivalent to running:

kubectl rollout undo deployment/{name} -n {namespace}

Note: This operation requires at least one previous revision to exist. If the deployment has never been updated, the rollback will fail.

Authorizations:
bearerAuth
path Parameters
namespace
required
string
Example: default

Deployment namespace

name
required
string
Example: nginx-deployment

Deployment name

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Deployment default/nginx-deployment has been rolled back to revision 2",
  • "deployment": {
    }
}

Update container images in a deployment

Update one or more container images in a deployment.

This operation performs a strategic merge patch to update specific container images without affecting other deployment settings. The update triggers a rolling update to replace pods with the new images.

This is equivalent to running:

kubectl set image deployment/{name} container1=image1 container2=image2 -n {namespace}

Note: Container names must match existing containers in the deployment.

Authorizations:
bearerAuth
path Parameters
namespace
required
string
Example: default

Deployment namespace

name
required
string
Example: nginx-deployment

Deployment name

Request Body schema: application/json
required

Array of container name to image mappings. Each object in the array should have a single key-value pair where:

  • Key: container name (must exist in the deployment)
  • Value: new image to use (including tag)
Array (non-empty)
property name*
additional property
string

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Successfully updated images for deployment default/nginx-deployment",
  • "updated_images": {
    },
  • "deployment": {
    }
}

Get detailed service information

Get detailed information about a specific service in a namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns service wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
namespace
required
string

Service namespace

name
required
string

Service name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "service_detail": {
    },
  • "error": {
    }
}

Update a Service

Update an existing Service

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Service namespace

name
required
string

Service name

Request Body schema:
required

Service specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "v1",
  • "kind": "Service",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Delete a Service

Delete a specific Service

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Service namespace

name
required
string

Service name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get detailed ingress information

Get detailed information about a specific ingress in a namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns ingress wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
namespace
required
string

Ingress namespace

name
required
string

Ingress name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "ingress_detail": {
    },
  • "error": {
    }
}

Update an Ingress

Update an existing Ingress

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Ingress namespace

name
required
string

Ingress name

Request Body schema:
required

Ingress specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "networking.k8s.io/v1",
  • "kind": "Ingress",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Delete an Ingress

Delete a specific Ingress

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Ingress namespace

name
required
string

Ingress name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get detailed PVC information

Get detailed information about a specific PersistentVolumeClaim in a namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns PVC wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
namespace
required
string

PVC namespace

name
required
string

PVC name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "pvc_detail": {
    },
  • "error": {
    }
}

Delete a PVC

Delete a specific PersistentVolumeClaim

Authorizations:
bearerAuth
path Parameters
namespace
required
string

PVC namespace

name
required
string

PVC name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get detailed PV information

Get detailed information about a specific PersistentVolume.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns PV wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
name
required
string

PV name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "pv_detail": {
    },
  • "error": {
    }
}

Delete a PV

Delete a specific PersistentVolume

Authorizations:
bearerAuth
path Parameters
name
required
string

PV name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get detailed secret information

Get detailed information about a specific secret in a namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns secret wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
namespace
required
string

Secret namespace

name
required
string

Secret name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "secret_detail": {
    },
  • "error": {
    }
}

Update a Secret

Update an existing Secret

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Secret namespace

name
required
string

Secret name

Request Body schema:
required

Secret specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "v1",
  • "kind": "Secret",
  • "metadata": {
    },
  • "data": {
    },
  • "type": "Opaque"
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Delete a Secret

Delete a specific Secret

Authorizations:
bearerAuth
path Parameters
namespace
required
string

Secret namespace

name
required
string

Secret name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get detailed ConfigMap information

Get detailed information about a specific ConfigMap in a namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns ConfigMap wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
namespace
required
string

ConfigMap namespace

name
required
string

ConfigMap name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "configmap_detail": {
    },
  • "error": {
    }
}

Update a ConfigMap

Update an existing ConfigMap

Authorizations:
bearerAuth
path Parameters
namespace
required
string

ConfigMap namespace

name
required
string

ConfigMap name

Request Body schema:
required

ConfigMap specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "v1",
  • "kind": "ConfigMap",
  • "metadata": {
    },
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Delete a ConfigMap

Delete a specific ConfigMap

Authorizations:
bearerAuth
path Parameters
namespace
required
string

ConfigMap namespace

name
required
string

ConfigMap name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get detailed Namespace information

Get detailed information about a specific Namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns Namespace wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
name
required
string

Namespace name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "namespace_detail": {
    },
  • "error": {
    }
}

Update a Namespace

Update an existing Namespace

Authorizations:
bearerAuth
path Parameters
name
required
string

Namespace name

Request Body schema:
required

Namespace specification in JSON or YAML format

property name*
additional property
any

Responses

Request samples

Content type
{
  • "apiVersion": "v1",
  • "kind": "Namespace",
  • "metadata": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "status": "error"
}

Delete a Namespace

Delete a specific Namespace

Authorizations:
bearerAuth
path Parameters
name
required
string

Namespace name

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Get detailed Node information

Get detailed information about a specific Node.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns Node wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
name
required
string

Node name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "node_detail": {
    },
  • "error": {
    }
}

Cordon a Kubernetes node

Marks a node as unschedulable, preventing new pods from being scheduled on it

Authorizations:
bearerAuth
path Parameters
name
required
string

Node name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "Node worker-1 cordoned successfully"
}

Uncordon a Kubernetes node

Marks a node as schedulable, allowing new pods to be scheduled on it

Authorizations:
bearerAuth
path Parameters
name
required
string

Node name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "Node worker-1 uncordoned successfully"
}

Drain a Kubernetes node

Safely evicts all pods from a node before maintenance

Authorizations:
bearerAuth
path Parameters
name
required
string

Node name

Request Body schema: application/json
optional
gracePeriodSeconds
integer
Default: 30

Grace period for pod eviction

timeout
integer
Default: 300

Timeout for drain operation in seconds

ignoreDaemonSets
boolean
Default: true

Ignore DaemonSet-managed pods

deleteEmptyDirData
boolean
Default: false

Allow deletion of pods with emptyDir volumes

Responses

Request samples

Content type
application/json
{
  • "gracePeriodSeconds": 30,
  • "timeout": 300,
  • "ignoreDaemonSets": true,
  • "deleteEmptyDirData": false
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "Node worker-1 drained successfully"
}

Get detailed DaemonSet information

Get detailed information about a specific DaemonSet in a namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns DaemonSet wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
namespace
required
string

DaemonSet namespace

name
required
string

DaemonSet name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "daemonset_detail": {
    },
  • "error": {
    }
}

Restart DaemonSet pods

Trigger a rolling restart of all pods managed by a DaemonSet.

This operation works by adding or updating a restart annotation (kubectl.kubernetes.io/restartedAt) on the DaemonSet's pod template, which triggers Kubernetes to perform a rolling update with new pods.

This is equivalent to running:

kubectl rollout restart daemonset/{name} -n {namespace}

Note: DaemonSets update pods on each node according to the update strategy. By default, this is a rolling update that respects maxUnavailable settings.

Authorizations:
bearerAuth
path Parameters
namespace
required
string
Example: kube-system

DaemonSet namespace

name
required
string
Example: fluentd

DaemonSet name

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "DaemonSet kube-system/fluentd has been restarted",
  • "daemonset": {
    }
}

Rollback DaemonSet to previous revision

Rollback a DaemonSet to its previous revision.

This operation retrieves the previous revision from the DaemonSet's ControllerRevisions and updates the DaemonSet to use the pod template from that previous revision. The rollback triggers a rolling update to replace current pods with pods from the previous configuration.

This is equivalent to running:

kubectl rollout undo daemonset/{name} -n {namespace}

Note: This operation requires at least one previous revision to exist. DaemonSets use ControllerRevisions to track their history.

Authorizations:
bearerAuth
path Parameters
namespace
required
string
Example: kube-system

DaemonSet namespace

name
required
string
Example: fluentd

DaemonSet name

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "DaemonSet kube-system/fluentd has been rolled back to revision 2",
  • "daemonset": {
    }
}

Update container images in a DaemonSet

Update one or more container images in a DaemonSet.

This operation performs a strategic merge patch to update specific container images without affecting other DaemonSet settings. The update triggers a rolling update to replace pods with the new images.

This is equivalent to running:

kubectl set image daemonset/{name} container1=image1 container2=image2 -n {namespace}

Note: Container names must match existing containers in the DaemonSet. The update will be applied to all pods managed by the DaemonSet across all nodes.

Authorizations:
bearerAuth
path Parameters
namespace
required
string
Example: kube-system

DaemonSet namespace

name
required
string
Example: fluentd

DaemonSet name

Request Body schema: application/json
required

Array of container name to image mappings. Each object in the array should have a single key-value pair where:

  • Key: container name (must exist in the DaemonSet)
  • Value: new image to use (including tag)
Array (non-empty)
property name*
additional property
string

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Successfully updated images for DaemonSet kube-system/fluentd",
  • "updated_images": {
    },
  • "daemonset": {
    }
}

Get detailed StatefulSet information

Get detailed information about a specific StatefulSet in a namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns StatefulSet wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
namespace
required
string

StatefulSet namespace

name
required
string

StatefulSet name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "statefulset_detail": {
    },
  • "error": {
    }
}

Restart StatefulSet pods

Trigger a rolling restart of all pods managed by a StatefulSet.

This operation works by adding or updating a restart annotation (kubectl.kubernetes.io/restartedAt) on the StatefulSet's pod template, which triggers Kubernetes to perform a rolling update with new pods.

This is equivalent to running:

kubectl rollout restart statefulset/{name} -n {namespace}

Note: StatefulSets update pods in order, one at a time, respecting the updateStrategy settings. Pods are updated in reverse ordinal order (from highest to lowest) by default.

Authorizations:
bearerAuth
path Parameters
namespace
required
string
Example: default

StatefulSet namespace

name
required
string
Example: mysql

StatefulSet name

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "StatefulSet default/mysql has been restarted",
  • "statefulset": {
    }
}

Rollback StatefulSet to previous revision

Rollback a StatefulSet to its previous revision.

This operation retrieves the previous revision from the StatefulSet's ControllerRevisions and updates the StatefulSet to use the pod template from that previous revision. The rollback triggers an ordered update to replace current pods with pods from the previous configuration.

This is equivalent to running:

kubectl rollout undo statefulset/{name} -n {namespace}

Note: This operation requires at least one previous revision to exist. StatefulSets use ControllerRevisions to track their history. Pods will be updated in reverse ordinal order, maintaining the StatefulSet's ordering guarantees.

Authorizations:
bearerAuth
path Parameters
namespace
required
string
Example: default

StatefulSet namespace

name
required
string
Example: mysql

StatefulSet name

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "StatefulSet default/mysql has been rolled back to revision 2",
  • "statefulset": {
    }
}

Update container images in a StatefulSet

Update one or more container images in a StatefulSet.

This operation performs a strategic merge patch to update specific container images without affecting other StatefulSet settings. The update triggers an ordered rolling update to replace pods with the new images.

This is equivalent to running:

kubectl set image statefulset/{name} container1=image1 container2=image2 -n {namespace}

Note: Container names must match existing containers in the StatefulSet. Pods will be updated in reverse ordinal order (highest to lowest) according to the StatefulSet's updateStrategy. This ensures stable network identities and storage are maintained.

Authorizations:
bearerAuth
path Parameters
namespace
required
string
Example: default

StatefulSet namespace

name
required
string
Example: mysql

StatefulSet name

Request Body schema: application/json
required

Array of container name to image mappings. Each object in the array should have a single key-value pair where:

  • Key: container name (must exist in the StatefulSet)
  • Value: new image to use (including tag)
Array (non-empty)
property name*
additional property
string

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Successfully updated images for StatefulSet default/mysql",
  • "updated_images": {
    },
  • "statefulset": {
    }
}

Get detailed Job information

Get detailed information about a specific Job in a namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns Job wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
namespace
required
string

Job namespace

name
required
string

Job name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "job_detail": {
    },
  • "error": {
    }
}

Get detailed CronJob information

Get detailed information about a specific CronJob in a namespace.

Supports both JSON and YAML response formats based on the Accept header:

  • application/json (default) - Returns CronJob wrapped in API response
  • application/yaml, text/yaml, application/x-yaml - Returns raw Kubernetes YAML with cleaned metadata

When YAML format is requested, the following fields are automatically removed for cleaner output:

  • metadata.managedFields - Verbose internal field tracking
  • metadata.selfLink - Deprecated field
  • metadata.uid - Auto-generated identifier
Authorizations:
bearerAuth
path Parameters
namespace
required
string

CronJob namespace

name
required
string

CronJob name

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/yaml" "application/x-yaml" "application/yml" "text/yaml" "text/yml" "text/x-yaml"

Response format preference. Supported values:

  • application/json (default)
  • application/yaml
  • application/x-yaml
  • application/yml
  • text/yaml
  • text/yml
  • text/x-yaml

Responses

Response samples

Content type
{
  • "status": "success",
  • "cronjob_detail": {
    },
  • "error": {
    }
}

Helm

List Helm releases

List all Helm releases from all namespaces in the Kubernetes cluster by default. Use namespace parameter to filter to a specific namespace.

Authorizations:
bearerAuth
query Parameters
namespace
string
Example: namespace=default

Filter releases by specific namespace (overrides default all-namespace behavior)

all
boolean
Default: true

Explicitly control whether to show releases from all namespaces (default: true)

filter
string
Example: filter=nginx

Filter releases by name pattern

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List Helm charts

Search all Helm charts from configured repositories (equivalent to 'helm search repo -l')

Authorizations:
bearerAuth
query Parameters
repository
string
Example: repository=bitnami

Filter charts by repository name

all_versions
boolean
Default: true

Show all versions of charts (equivalent to -l flag in helm search)

devel
boolean
Default: false

Include development versions (equivalent to --devel flag)

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List Helm repositories

List all configured Helm repositories (equivalent to 'helm repo list')

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{}

Add a new Helm repository

Add a new Helm repository to the configuration (equivalent to 'helm repo add')

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string non-empty

Name to assign to the repository

url
required
string <uri>

URL of the Helm repository

username
string

Username for authenticated repositories

password
string

Password for authenticated repositories

cert_file
string

Path to TLS certificate file

key_file
string

Path to TLS key file

ca_file
string

Path to CA bundle file

insecure_skip_tls_verify
boolean
Default: false

Skip TLS certificate verification

pass_credentials_all
boolean
Default: false

Pass credentials to all domains

force_update
boolean
Default: false

Force update the repository if it already exists

Responses

Request samples

Content type
application/json
{
  • "name": "bitnami",
  • "url": "https://charts.bitnami.com/bitnami",
  • "username": "",
  • "password": "",
  • "cert_file": "",
  • "key_file": "",
  • "ca_file": "",
  • "insecure_skip_tls_verify": false,
  • "pass_credentials_all": false,
  • "force_update": false
}

Response samples

Content type
application/json
{}

Update a Helm repository

Update a specific Helm repository to fetch the latest charts (equivalent to 'helm repo update {repo-name}')

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: bitnami

Name of the repository to update

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Ansible

List all playbooks

Returns a list of all available Ansible playbooks in the system

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get playbook details

Returns detailed information about a specific playbook including its content

Authorizations:
bearerAuth
path Parameters
name
required
string

Name of the playbook

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete playbook

Deletes a playbook from the system

Authorizations:
bearerAuth
path Parameters
name
required
string

Name of the playbook to delete

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Upload playbook

Uploads a new playbook to the server

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Name of the playbook file

content
required
string

Base64 encoded playbook content

overwrite
boolean
Default: false

Whether to overwrite existing playbook

Responses

Request samples

Content type
application/json
{
  • "name": "deploy.yml",
  • "content": "LS0tCi0gbmFtZTogRGVwbG95IGFwcGxpY2F0aW9uCiAgaG9zdHM6IGFsbAogIHRhc2tzOgogICAgLSBuYW1lOiBVcGRhdGUgYXBwCiAgICAgIGNvbW1hbmQ6IC9iaW4vdXBkYXRlLnNo",
  • "overwrite": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Validate playbook

Validates playbook syntax using ansible-playbook --syntax-check

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Name of the playbook to validate

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Run playbook

Executes an Ansible playbook with specified parameters

Authorizations:
bearerAuth
Request Body schema: application/json
required
playbook
required
string

Name of the playbook to run

inventory
string

Inventory to use (name or content)

limit
string

Limit execution to specific hosts/groups

tags
Array of strings

Run only tasks with these tags

skip_tags
Array of strings

Skip tasks with these tags

object

Extra variables to pass to playbook

check
boolean
Default: false

Run in check mode (dry run)

diff
boolean
Default: false

Show differences

verbose
integer [ 0 .. 4 ]
Default: 0

Verbosity level (0-4)

become
boolean
Default: false

Run with become (sudo)

become_user
string

User to become

private_key
string

Path to SSH private key

timeout
integer
Default: 10

Connection timeout in seconds

forks
integer
Default: 5

Number of parallel processes

Responses

Request samples

Content type
application/json
{
  • "playbook": "site.yml",
  • "inventory": "production",
  • "limit": "webservers",
  • "tags": [
    ],
  • "skip_tags": [
    ],
  • "extra_vars": {
    },
  • "check": false,
  • "diff": true,
  • "verbose": 2,
  • "become": true,
  • "become_user": "root",
  • "private_key": "/home/user/.ssh/id_rsa",
  • "timeout": 30,
  • "forks": 10
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get playbook templates

Returns a list of available playbook templates

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create playbook from template

Creates a new playbook from a template with variable substitution

Authorizations:
bearerAuth
Request Body schema: application/json
required
template_id
required
string

Template identifier

name
required
string

Name for the new playbook

object

Template variable values

Responses

Request samples

Content type
application/json
{
  • "template_id": "nginx-setup",
  • "name": "production-nginx.yml",
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Sync playbooks from Git

Syncs playbooks from a Git repository

Authorizations:
bearerAuth
Request Body schema: application/json
required
url
required
string <uri>

Git repository URL

branch
string
Default: "main"

Git branch to sync

path
string

Path within repository

auth_token
string

Authentication token for private repos

ssh_key
string

SSH private key for authentication

sync_as_symlink
boolean
Default: false

Create symlink instead of copying

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Install from Ansible Galaxy

Installs roles or collections from Ansible Galaxy

Authorizations:
bearerAuth
Request Body schema: application/json
required
type
string
Enum: "role" "collection"

Resource type to install

name
string

Name of role/collection

version
string

Version to install

requirements_file
string

Path to requirements file

force
boolean
Default: false

Force reinstall

Responses

Request samples

Content type
application/json
{
  • "type": "collection",
  • "name": "community.general",
  • "version": "5.0.0",
  • "requirements_file": "requirements.yml",
  • "force": false
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Download playbook from URL

Downloads a playbook from a URL

Authorizations:
bearerAuth
Request Body schema: application/json
required
url
required
string <uri>

URL of the playbook to download

name
required
string

Name to save the playbook as

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Run ad-hoc command

Executes an ad-hoc Ansible command

Authorizations:
bearerAuth
Request Body schema: application/json
required
hosts
required
string

Host pattern to run against

module
required
string

Ansible module to run

args
string

Module arguments

inventory
string

Inventory to use

object

Extra variables

become
boolean
Default: false

Run with become (sudo)

verbose
integer [ 0 .. 4 ]
Default: 0

Verbosity level

forks
integer
Default: 5

Number of parallel processes

Responses

Request samples

Content type
application/json
{
  • "hosts": "all",
  • "module": "ping",
  • "args": "data=pong",
  • "inventory": "production",
  • "extra_vars": {
    },
  • "become": false,
  • "verbose": 0,
  • "forks": 5
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List executions

Returns a list of all Ansible execution results

Authorizations:
bearerAuth
query Parameters
status
string
Enum: "running" "success" "failed"

Filter by execution status

type
string
Enum: "playbook" "adhoc"

Filter by execution type

limit
integer
Default: 100

Maximum number of results to return

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get execution details

Returns detailed information about a specific execution

Authorizations:
bearerAuth
path Parameters
id
required
string

Execution ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Cancel execution

Cancels a running execution (not yet implemented)

Authorizations:
bearerAuth
path Parameters
id
required
string

Execution ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Stream execution output

Establishes a WebSocket connection to stream real-time execution output.

WebSocket URL: ws://localhost:8080/api/v1/ansible/executions/{id}/stream

Authentication: Send JWT token as query parameter or in first message.

Message Format:

{
  "type": "output",
  "content": "TASK [Update packages] *****",
  "time": 1705315800
}

Completion Message:

{
  "type": "complete",
  "result": {
    "id": "exec-123456",
    "status": "success",
    "exit_code": 0
  }
}
Authorizations:
bearerAuth
path Parameters
id
required
string

Execution ID

Responses

Response samples

Content type
application/json
{
  • "status": "error"
}

Generate dynamic inventory

Generates a dynamic inventory from current system state

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Save inventory

Saves an inventory configuration

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Inventory name

content
required
string

Inventory content (INI or YAML format)

format
string
Default: "ini"
Enum: "ini" "yaml" "json"

Inventory format

Responses

Request samples

Content type
application/json
{
  • "name": "production",
  • "content": "[webservers]\nweb1.example.com\nweb2.example.com\n\n[databases]\ndb1.example.com\n",
  • "format": "ini"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get inventory

Retrieves a saved inventory (not yet implemented)

Authorizations:
bearerAuth
path Parameters
name
required
string

Inventory name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List scheduled tasks

Returns all scheduled Ansible tasks (not yet implemented)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Create scheduled task

Creates a scheduled playbook execution (not yet implemented)

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Schedule name

playbook
required
string

Playbook to run

cron
required
string

Cron expression

enabled
boolean
Default: true

Enable schedule immediately

object (PlaybookRunRequest)
timezone
string
Default: "UTC"

Timezone for schedule

Responses

Request samples

Content type
application/json
{
  • "name": "Daily backup",
  • "playbook": "backup.yml",
  • "cron": "0 2 * * *",
  • "enabled": true,
  • "parameters": {
    },
  • "timezone": "America/New_York"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Delete scheduled task

Deletes a scheduled task (not yet implemented)

Authorizations:
bearerAuth
path Parameters
id
required
string

Schedule ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}