The server API from Incus — 5 operation(s) for server.
swagger: '2.0'
info:
contact:
email: lxc-devel@lists.linuxcontainers.org
name: Incus upstream
url: https://github.com/lxc/incus
description: 'This is the REST API used by all Incus clients.
Internal endpoints aren''t included in this documentation.
The Incus API is available over both a local unix+http and remote https API.
Authentication for local users relies on group membership and access to the unix socket.
For remote users, the default authentication method is TLS client
certificates.'
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0
title: Incus external REST certificates server API
version: '1.0'
tags:
- name: server
paths:
/:
get:
description: 'Returns a list of supported API versions (URLs).
Internal API endpoints are not reported as those aren''t versioned
and should only be used by the daemon itself.'
operationId: api_get
produces:
- application/json
responses:
'200':
description: API endpoints
schema:
description: Sync response
properties:
metadata:
description: List of endpoints
example:
- /1.0
items:
type: string
type: array
status:
description: Status description
example: Success
type: string
status_code:
description: Status code
example: 200
type: integer
type:
description: Response type
example: sync
type: string
type: object
summary: Get the supported API endpoints
tags:
- server
/1.0:
get:
description: Shows the full server environment and configuration.
operationId: server_get
parameters:
- description: Cluster member name
example: server01
in: query
name: target
type: string
- description: Project name
example: default
in: query
name: project
type: string
produces:
- application/json
responses:
'200':
description: Server environment and configuration
schema:
description: Sync response
properties:
metadata:
$ref: '#/definitions/Server'
status:
description: Status description
example: Success
type: string
status_code:
description: Status code
example: 200
type: integer
type:
description: Response type
example: sync
type: string
type: object
'500':
$ref: '#/responses/InternalServerError'
summary: Get the server environment and configuration
tags:
- server
patch:
consumes:
- application/json
description: Updates a subset of the server configuration.
operationId: server_patch
parameters:
- description: Cluster member name
example: server01
in: query
name: target
type: string
- description: Server configuration
in: body
name: server
required: true
schema:
$ref: '#/definitions/ServerPut'
produces:
- application/json
responses:
'200':
$ref: '#/responses/EmptySyncResponse'
'400':
$ref: '#/responses/BadRequest'
'403':
$ref: '#/responses/Forbidden'
'412':
$ref: '#/responses/PreconditionFailed'
'500':
$ref: '#/responses/InternalServerError'
summary: Partially update the server configuration
tags:
- server
put:
consumes:
- application/json
description: Updates the entire server configuration.
operationId: server_put
parameters:
- description: Cluster member name
example: server01
in: query
name: target
type: string
- description: Server configuration
in: body
name: server
required: true
schema:
$ref: '#/definitions/ServerPut'
produces:
- application/json
responses:
'200':
$ref: '#/responses/EmptySyncResponse'
'400':
$ref: '#/responses/BadRequest'
'403':
$ref: '#/responses/Forbidden'
'412':
$ref: '#/responses/PreconditionFailed'
'500':
$ref: '#/responses/InternalServerError'
summary: Update the server configuration
tags:
- server
/1.0/events:
get:
description: Connects to the event API using websocket.
operationId: events_get
parameters:
- description: Project name
example: default
in: query
name: project
type: string
- description: Event type(s), comma separated (valid types are logging, operation or lifecycle)
example: logging,lifecycle
in: query
name: type
type: string
- description: Retrieve instances from all projects
in: query
name: all-projects
type: boolean
produces:
- application/json
responses:
'200':
description: Websocket message (JSON)
schema:
$ref: '#/definitions/Event'
'403':
$ref: '#/responses/Forbidden'
'500':
$ref: '#/responses/InternalServerError'
summary: Get the event stream
tags:
- server
/1.0/resources:
get:
description: Gets the hardware information profile of the server.
operationId: resources_get
parameters:
- description: Cluster member name
example: server01
in: query
name: target
type: string
produces:
- application/json
responses:
'200':
description: Hardware resources
schema:
description: Sync response
properties:
metadata:
$ref: '#/definitions/Resources'
status:
description: Status description
example: Success
type: string
status_code:
description: Status code
example: 200
type: integer
type:
description: Response type
example: sync
type: string
type: object
'403':
$ref: '#/responses/Forbidden'
'500':
$ref: '#/responses/InternalServerError'
summary: Get system resources information
tags:
- server
/1.0?public:
get:
description: 'Shows a small subset of the server environment and configuration
which is required by untrusted clients to reach a server.
The `?public` part of the URL isn''t required, it''s simply used to
separate the two behaviors of this endpoint.'
operationId: server_get_untrusted
produces:
- application/json
responses:
'200':
description: Server environment and configuration
schema:
description: Sync response
properties:
metadata:
$ref: '#/definitions/ServerUntrusted'
status:
description: Status description
example: Success
type: string
status_code:
description: Status code
example: 200
type: integer
type:
description: Response type
example: sync
type: string
type: object
'500':
$ref: '#/responses/InternalServerError'
summary: Get the server environment
tags:
- server
definitions:
ResourcesPCI:
description: ResourcesPCI represents the PCI devices available on the system
properties:
devices:
description: List of PCI devices
items:
$ref: '#/definitions/ResourcesPCIDevice'
type: array
x-go-name: Devices
total:
description: Total number of PCI devices
example: 1
format: uint64
type: integer
x-go-name: Total
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesNetwork:
description: ResourcesNetwork represents the network cards available on the system
properties:
cards:
description: List of network cards
items:
$ref: '#/definitions/ResourcesNetworkCard'
type: array
x-go-name: Cards
total:
description: Total number of network cards
example: 1
format: uint64
type: integer
x-go-name: Total
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesGPUCardSRIOV:
description: ResourcesGPUCardSRIOV represents the SRIOV configuration of the GPU
properties:
current_vfs:
description: Number of VFs currently configured
example: 0
format: uint64
type: integer
x-go-name: CurrentVFs
maximum_vfs:
description: Maximum number of supported VFs
example: 0
format: uint64
type: integer
x-go-name: MaximumVFs
vfs:
description: List of VFs (as additional GPU devices)
example: null
items:
$ref: '#/definitions/ResourcesGPUCard'
type: array
x-go-name: VFs
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesCPUSocket:
description: ResourcesCPUSocket represents a CPU socket on the system
properties:
address_sizes:
$ref: '#/definitions/ResourcesCPUAddressSizes'
cache:
description: List of CPU caches
items:
$ref: '#/definitions/ResourcesCPUCache'
type: array
x-go-name: Cache
cores:
description: List of CPU cores
items:
$ref: '#/definitions/ResourcesCPUCore'
type: array
x-go-name: Cores
frequency:
description: Current CPU frequency (Mhz)
example: 3499
format: uint64
type: integer
x-go-name: Frequency
frequency_minimum:
description: Minimum CPU frequency (Mhz)
example: 400
format: uint64
type: integer
x-go-name: FrequencyMinimum
frequency_turbo:
description: Maximum CPU frequency (Mhz)
example: 3500
format: uint64
type: integer
x-go-name: FrequencyTurbo
name:
description: Product name
example: Intel(R) Core(TM) i5-7300U CPU @ 2.60GHz
type: string
x-go-name: Name
socket:
description: Socket number
example: 0
format: uint64
type: integer
x-go-name: Socket
vendor:
description: Vendor name
example: GenuineIntel
type: string
x-go-name: Vendor
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ServerStorageDriverInfo:
description: ServerStorageDriverInfo represents the read-only info about a storage driver
properties:
Name:
description: Name of the driver
example: zfs
type: string
Remote:
description: Whether the driver has remote volumes
example: false
type: boolean
Version:
description: Version of the driver
example: 0.8.4-1ubuntu11
type: string
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesCPUAddressSizes:
properties:
physical_bits:
format: uint64
type: integer
x-go-name: PhysicalBits
virtual_bits:
format: uint64
type: integer
x-go-name: VirtualBits
title: ResourcesCPUAddressSizes resprents address size information for a CPU socket.
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesGPUCard:
description: ResourcesGPUCard represents a GPU card on the system
properties:
driver:
description: Kernel driver currently associated with the GPU
example: i915
type: string
x-go-name: Driver
driver_version:
description: Version of the kernel driver
example: 5.8.0-36-generic
type: string
x-go-name: DriverVersion
drm:
$ref: '#/definitions/ResourcesGPUCardDRM'
mdev:
additionalProperties:
$ref: '#/definitions/ResourcesGPUCardMdev'
description: Map of available mediated device profiles
example: null
type: object
x-go-name: Mdev
numa_node:
description: NUMA node the GPU is a part of
example: 0
format: uint64
type: integer
x-go-name: NUMANode
nvidia:
$ref: '#/definitions/ResourcesGPUCardNvidia'
pci_address:
description: PCI address
example: '0000:00:02.0'
type: string
x-go-name: PCIAddress
product:
description: Name of the product
example: HD Graphics 620
type: string
x-go-name: Product
product_id:
description: PCI ID of the product
example: '5916'
type: string
x-go-name: ProductID
sriov:
$ref: '#/definitions/ResourcesGPUCardSRIOV'
usb_address:
description: USB address (for USB cards)
example: '2:7'
type: string
x-go-name: USBAddress
vendor:
description: Name of the vendor
example: Intel Corporation
type: string
x-go-name: Vendor
vendor_id:
description: PCI ID of the vendor
example: '8086'
type: string
x-go-name: VendorID
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesUSB:
description: ResourcesUSB represents the USB devices available on the system
properties:
devices:
description: List of USB devices
items:
$ref: '#/definitions/ResourcesUSBDevice'
type: array
x-go-name: Devices
total:
description: Total number of USB devices
example: 1
format: uint64
type: integer
x-go-name: Total
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesNetworkCardSRIOV:
description: ResourcesNetworkCardSRIOV represents the SRIOV configuration of the network card
properties:
current_vfs:
description: Number of VFs currently configured
example: 0
format: uint64
type: integer
x-go-name: CurrentVFs
maximum_vfs:
description: Maximum number of supported VFs
example: 0
format: uint64
type: integer
x-go-name: MaximumVFs
vfs:
description: List of VFs (as additional Network devices)
example: null
items:
$ref: '#/definitions/ResourcesNetworkCard'
type: array
x-go-name: VFs
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesNetworkCardVDPA:
description: ResourcesNetworkCardVDPA represents the VDPA configuration of the network card
properties:
device:
description: Device identifier of the VDPA device
type: string
x-go-name: Device
name:
description: Name of the VDPA device
type: string
x-go-name: Name
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesStorageDiskPartition:
description: ResourcesStorageDiskPartition represents a partition on a disk
properties:
device:
description: Device number
example: '259:1'
type: string
x-go-name: Device
id:
description: ID of the partition (device name)
example: nvme0n1p1
type: string
x-go-name: ID
partition:
description: Partition number
example: 1
format: uint64
type: integer
x-go-name: Partition
read_only:
description: Whether the partition is read-only
example: false
type: boolean
x-go-name: ReadOnly
size:
description: Size of the partition (bytes)
example: 254933278208
format: uint64
type: integer
x-go-name: Size
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesMemory:
description: ResourcesMemory represents the memory resources available on the system
properties:
hugepages_size:
description: Size of memory huge pages (bytes)
example: 2097152
format: uint64
type: integer
x-go-name: HugepagesSize
hugepages_total:
description: Total of memory huge pages (bytes)
example: 429284917248
format: uint64
type: integer
x-go-name: HugepagesTotal
hugepages_used:
description: Used memory huge pages (bytes)
example: 429284917248
format: uint64
type: integer
x-go-name: HugepagesUsed
nodes:
description: List of NUMA memory nodes
example: null
items:
$ref: '#/definitions/ResourcesMemoryNode'
type: array
x-go-name: Nodes
total:
description: Total system memory (bytes)
example: 687194767360
format: uint64
type: integer
x-go-name: Total
used:
description: Used system memory (bytes)
example: 557450502144
format: uint64
type: integer
x-go-name: Used
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesPCIDevice:
description: ResourcesPCIDevice represents a PCI device
properties:
driver:
description: Kernel driver currently associated with the GPU
example: mgag200
type: string
x-go-name: Driver
driver_version:
description: Version of the kernel driver
example: 5.8.0-36-generic
type: string
x-go-name: DriverVersion
iommu_group:
description: IOMMU group number
example: 20
format: uint64
type: integer
x-go-name: IOMMUGroup
numa_node:
description: NUMA node the card is a part of
example: 0
format: uint64
type: integer
x-go-name: NUMANode
pci_address:
description: PCI address
example: '0000:07:03.0'
type: string
x-go-name: PCIAddress
product:
description: Name of the product
example: MGA G200eW WPCM450
type: string
x-go-name: Product
product_id:
description: PCI ID of the product
example: '0532'
type: string
x-go-name: ProductID
vendor:
description: Name of the vendor
example: Matrox Electronics Systems Ltd.
type: string
x-go-name: Vendor
vendor_id:
description: PCI ID of the vendor
example: 102b
type: string
x-go-name: VendorID
vpd:
$ref: '#/definitions/ResourcesPCIVPD'
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesPCIVPD:
description: ResourcesPCIVPD represents VPD entries for a device
properties:
entries:
additionalProperties:
type: string
description: Vendor provided key/value pairs.
example: '{"EC": ""A-5545", "MN": "103C", "V0": "5W PCIeGen2"}'
type: object
x-go-name: Entries
product_name:
description: Hardware provided product name.
example: HP Ethernet 1Gb 4-port 331i Adapter
type: string
x-go-name: ProductName
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesSystemChassis:
description: ResourcesSystemChassis represents the system chassis
properties:
serial:
description: Chassis serial number
example: PY3DD4X9
type: string
x-go-name: Serial
type:
description: Chassis type
example: Notebook
type: string
x-go-name: Type
vendor:
description: Chassis vendor
example: Lenovo
type: string
x-go-name: Vendor
version:
description: Chassis version/revision
example: None
type: string
x-go-name: Version
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ServerUntrusted:
description: ServerUntrusted represents a server configuration for an untrusted client
properties:
api_extensions:
description: List of supported API extensions
example:
- etag
- patch
- network
- storage
items:
type: string
readOnly: true
type: array
x-go-name: APIExtensions
api_status:
description: Support status of the current API (one of "devel", "stable" or "deprecated")
example: stable
readOnly: true
type: string
x-go-name: APIStatus
api_version:
description: API version number
example: '1.0'
readOnly: true
type: string
x-go-name: APIVersion
auth:
description: Whether the client is trusted (one of "trusted" or "untrusted")
example: untrusted
readOnly: true
type: string
x-go-name: Auth
auth_methods:
description: List of supported authentication methods
example:
- tls
items:
type: string
readOnly: true
type: array
x-go-name: AuthMethods
config:
description: Server configuration map (refer to doc/server.md)
example:
core.https_address: :8443
type: object
x-go-name: Config
public:
description: Whether the server is public-only (only public endpoints are implemented)
example: false
readOnly: true
type: boolean
x-go-name: Public
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
Server:
description: Server represents a server configuration
properties:
api_extensions:
description: List of supported API extensions
example:
- etag
- patch
- network
- storage
items:
type: string
readOnly: true
type: array
x-go-name: APIExtensions
api_status:
description: Support status of the current API (one of "devel", "stable" or "deprecated")
example: stable
readOnly: true
type: string
x-go-name: APIStatus
api_version:
description: API version number
example: '1.0'
readOnly: true
type: string
x-go-name: APIVersion
auth:
description: Whether the client is trusted (one of "trusted" or "untrusted")
example: untrusted
readOnly: true
type: string
x-go-name: Auth
auth_methods:
description: List of supported authentication methods
example:
- tls
items:
type: string
readOnly: true
type: array
x-go-name: AuthMethods
auth_user_method:
description: The current API user login method
example: unix
readOnly: true
type: string
x-go-name: AuthUserMethod
auth_user_name:
description: The current API user identifier
example: uid=201105
readOnly: true
type: string
x-go-name: AuthUserName
config:
description: Server configuration map (refer to doc/server.md)
example:
core.https_address: :8443
type: object
x-go-name: Config
environment:
$ref: '#/definitions/ServerEnvironment'
public:
description: Whether the server is public-only (only public endpoints are implemented)
example: false
readOnly: true
type: boolean
x-go-name: Public
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
Resources:
description: Resources represents the system hardware resources
properties:
cpu:
$ref: '#/definitions/ResourcesCPU'
gpu:
$ref: '#/definitions/ResourcesGPU'
load:
$ref: '#/definitions/ResourcesLoad'
memory:
$ref: '#/definitions/ResourcesMemory'
network:
$ref: '#/definitions/ResourcesNetwork'
pci:
$ref: '#/definitions/ResourcesPCI'
serial:
$ref: '#/definitions/ResourcesSerial'
storage:
$ref: '#/definitions/ResourcesStorage'
system:
$ref: '#/definitions/ResourcesSystem'
usb:
$ref: '#/definitions/ResourcesUSB'
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesSystem:
description: ResourcesSystem represents the system
properties:
chassis:
$ref: '#/definitions/ResourcesSystemChassis'
family:
description: System family
example: ThinkPad X1 Carbon 5th
type: string
x-go-name: Family
firmware:
$ref: '#/definitions/ResourcesSystemFirmware'
motherboard:
$ref: '#/definitions/ResourcesSystemMotherboard'
product:
description: System model
example: 20HRCTO1WW
type: string
x-go-name: Product
serial:
description: System serial number
example: PY3DD4X9
type: string
x-go-name: Serial
sku:
description: 'System nanufacturer SKU
LENOVO_MT_20HR_BU_Think_FM_ThinkPad X1 Carbon 5th'
type: string
x-go-name: Sku
type:
description: System type (unknown, physical, virtual-machine, container, ...)
example: physical
type: string
x-go-name: Type
uuid:
description: System UUID
example: 7fa1c0cc-2271-11b2-a85c-aab32a05d71a
type: string
x-go-name: UUID
vendor:
description: System vendor
example: LENOVO
type: string
x-go-name: Vendor
version:
description: System version
example: ThinkPad X1 Carbon 5th
type: string
x-go-name: Version
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesCPUCore:
description: ResourcesCPUCore represents a CPU core on the system
properties:
core:
description: Core identifier within the socket
example: 0
format: uint64
type: integer
x-go-name: Core
die:
description: What die the CPU is a part of (for chiplet designs)
example: 0
format: uint64
type: integer
x-go-name: Die
flags:
description: List of CPU flags
example: []
items:
type: string
type: array
x-go-name: Flags
frequency:
description: Current frequency
example: 3500
format: uint64
type: integer
x-go-name: Frequency
threads:
description: List of threads
items:
$ref: '#/definitions/ResourcesCPUThread'
type: array
x-go-name: Threads
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesGPU:
description: ResourcesGPU represents the GPU resources available on the system
properties:
cards:
description: List of GPUs
items:
$ref: '#/definitions/ResourcesGPUCard'
type: array
x-go-name: Cards
total:
description: Total number of GPUs
example: 1
format: uint64
type: integer
x-go-name: Total
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesMemoryNode:
description: ResourcesMemoryNode represents the node-specific memory resources available on the system
properties:
hugepages_total:
description: Total of memory huge pages (bytes)
example: 214536552448
format: uint64
type: integer
x-go-name: HugepagesTotal
hugepages_used:
description: Used memory huge pages (bytes)
example: 214536552448
format: uint64
type: integer
x-go-name: HugepagesUsed
numa_node:
description: NUMA node identifier
example: 0
format: uint64
type: integer
x-go-name: NUMANode
total:
description: Total system memory (bytes)
example: 343597383680
format: uint64
type: integer
x-go-name: Total
used:
description: Used system memory (bytes)
example: 264880439296
format: uint64
type: integer
x-go-name: Used
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesCPUCache:
description: ResourcesCPUCache represents a CPU cache
properties:
level:
description: Cache level (usually a number from 1 to 3)
example: 1
format: uint64
type: integer
x-go-name: Level
size:
description: Size of the cache (in bytes)
example: 32768
format: uint64
type: integer
x-go-name: Size
type:
description: Type of cache (Data, Instruction, Unified, ...)
example: Data
type: string
x-go-name: Type
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesSerial:
description: ResourcesSerial represents the serial devices available on the system
properties:
devices:
description: List of serial devices
items:
$ref: '#/definitions/ResourcesSerialDevice'
type: array
x-go-name: Devices
total:
description: Total number of serial devices
example: 1
format: uint64
type: integer
x-go-name: Total
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesNetworkCardPort:
description: ResourcesNetworkCardPort represents a network port on the system
properties:
address:
description: MAC address
example: 00:23:a4:01:01:6f
type: string
x-go-name: Address
auto_negotiation:
description: Whether auto negotiation is used
example: true
type: boolean
x-go-name: AutoNegotiation
id:
description: Port identifier (interface name)
example: eth0
type: string
x-go-name: ID
infiniband:
$ref: '#/definitions/ResourcesNetworkCardPortInfiniband'
link_detected:
description: Whether a link was detected
example: true
type: boolean
x-go-name: LinkDetected
link_duplex:
description: Duplex type
example: full
type: string
x-go-name: LinkDuplex
link_speed:
description: Current speed (Mbit/s)
example: 10000
format: uint64
type: integer
x-go-name: LinkSpeed
port:
description: Port number
example: 0
format: uint64
type: integer
x-go-name: Port
port_type:
description: Current port type
example: twisted pair
type: string
x-go-name: PortType
protocol:
description: Transport protocol
example: ethernet
type: string
x-go-name: Protocol
supported_modes:
description: List of supported modes
example:
- 100baseT/Full
- 1000baseT/Full
- 2500baseT/Full
- 5000baseT/Full
- 10000baseT/Full
items:
type: string
type: array
x-go-name: SupportedModes
supported_ports:
description: List of supported port types
example:
- twisted pair
items:
type: string
type: array
x-go-name: SupportedPorts
transceiver_type:
description: Type of transceiver used
example: internal
type: string
x-go-name: TransceiverType
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ServerPut:
description: ServerPut represents the modifiable fields of a server configuration
properties:
config:
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/incus/refs/heads/main/openapi/incus-server-api-openapi.yml