The cluster API from Incus — 7 operation(s) for cluster.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/incus-cluster-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.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 Cluster API
version: '1.0'
tags:
- name: cluster
paths:
/1.0/cluster:
get:
description: Gets the current cluster configuration.
operationId: cluster_get
responses:
'200':
description: Cluster configuration
content:
application/json:
schema:
description: Sync response
properties:
metadata:
$ref: '#/components/schemas/Cluster'
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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get the cluster configuration
tags:
- cluster
put:
description: Updates the entire cluster configuration.
operationId: cluster_put
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'412':
$ref: '#/components/responses/PreconditionFailed'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Update the cluster configuration
tags:
- cluster
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterPut'
description: Cluster configuration
required: true
/1.0/cluster/certificate:
put:
description: Replaces existing cluster certificate and reloads each cluster member.
operationId: clustering_update_cert
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Update the certificate for the cluster
tags:
- cluster
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterCertificatePut'
description: Cluster certificate replace request
required: true
/1.0/cluster/groups:
post:
description: Creates a new cluster group.
operationId: cluster_groups_post
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Create a cluster group.
tags:
- cluster
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterGroupsPost'
description: Cluster group to create
required: true
/1.0/cluster/members:
get:
description: Returns a list of cluster members (URLs).
operationId: cluster_members_get
parameters:
- description: Collection filter
example: default
in: query
name: filter
schema:
type: string
responses:
'200':
description: API endpoints
content:
application/json:
schema:
description: Sync response
properties:
metadata:
description: List of endpoints
example: "[\n \"/1.0/cluster/members/server01\",\n \"/1.0/cluster/members/server02\"\n]"
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
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get the cluster members
tags:
- cluster
post:
description: Requests a join token to add a cluster member.
operationId: cluster_members_post
responses:
'202':
$ref: '#/components/responses/Operation'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Request a join token
tags:
- cluster
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterMembersPost'
description: Cluster member add request
required: true
/1.0/cluster/members/{name}:
delete:
description: Removes the member from the cluster.
operationId: cluster_member_delete
parameters:
- description: Cluster member name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Delete the cluster member
tags:
- cluster
get:
description: Gets a specific cluster member.
operationId: cluster_member_get
parameters:
- description: Cluster member name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
description: Cluster member
content:
application/json:
schema:
description: Sync response
properties:
metadata:
$ref: '#/components/schemas/ClusterMember'
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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get the cluster member
tags:
- cluster
patch:
description: Updates a subset of the cluster member configuration.
operationId: cluster_member_patch
parameters:
- description: Cluster member name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'412':
$ref: '#/components/responses/PreconditionFailed'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Partially update the cluster member
tags:
- cluster
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterMemberPut'
description: Cluster member configuration
required: true
post:
description: Renames an existing cluster member.
operationId: cluster_member_post
parameters:
- description: Cluster member name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Rename the cluster member
tags:
- cluster
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterMemberPost'
description: Cluster member rename request
required: true
put:
description: Updates the entire cluster member configuration.
operationId: cluster_member_put
parameters:
- description: Cluster member name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'412':
$ref: '#/components/responses/PreconditionFailed'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Update the cluster member
tags:
- cluster
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterMemberPut'
description: Cluster member configuration
required: true
/1.0/cluster/members/{name}/state:
get:
description: Gets state of a specific cluster member.
operationId: cluster_member_state_get
parameters:
- description: Cluster member name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
description: Cluster member state
content:
application/json:
schema:
description: Sync response
properties:
metadata:
$ref: '#/components/schemas/ClusterMemberState'
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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get state of the cluster member
tags:
- cluster
post:
description: Evacuates or restores a cluster member.
operationId: cluster_member_state_post
parameters:
- description: Cluster member name
in: path
name: name
required: true
schema:
type: string
responses:
'202':
$ref: '#/components/responses/Operation'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Evacuate or restore a cluster member
tags:
- cluster
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterMemberStatePost'
description: Cluster member state
required: true
/1.0/cluster/members?recursion=1:
get:
description: Returns a list of cluster members (structs).
operationId: cluster_members_get_recursion1
parameters:
- description: Collection filter
example: default
in: query
name: filter
schema:
type: string
responses:
'200':
description: API endpoints
content:
application/json:
schema:
description: Sync response
properties:
metadata:
description: List of cluster members
items:
$ref: '#/components/schemas/ClusterMember'
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
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get the cluster members
tags:
- cluster
components:
responses:
PreconditionFailed:
description: Precondition Failed
content:
application/json:
schema:
properties:
error:
example: precondition failed
type: string
x-go-name: Error
error_code:
example: 412
format: int64
type: integer
x-go-name: ErrorCode
type:
example: error
type: string
x-go-name: Type
type: object
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
properties:
error:
example: internal server error
type: string
x-go-name: Error
error_code:
example: 500
format: int64
type: integer
x-go-name: ErrorCode
type:
example: error
type: string
x-go-name: Type
type: object
BadRequest:
description: Bad Request
content:
application/json:
schema:
properties:
error:
example: bad request
type: string
x-go-name: Error
error_code:
example: 400
format: int64
type: integer
x-go-name: ErrorCode
type:
example: error
type: string
x-go-name: Type
type: object
EmptySyncResponse:
description: Empty sync response
content:
application/json:
schema:
properties:
status:
example: Success
type: string
x-go-name: Status
status_code:
example: 200
format: int64
type: integer
x-go-name: StatusCode
type:
example: sync
type: string
x-go-name: Type
type: object
Forbidden:
description: Forbidden
content:
application/json:
schema:
properties:
error:
example: not authorized
type: string
x-go-name: Error
error_code:
example: 403
format: int64
type: integer
x-go-name: ErrorCode
type:
example: error
type: string
x-go-name: Type
type: object
Operation:
description: Operation
content:
application/json:
schema:
properties:
metadata:
$ref: '#/components/schemas/Operation'
operation:
example: /1.0/operations/66e83638-9dd7-4a26-aef2-5462814869a1
type: string
x-go-name: Operation
status:
example: Operation created
type: string
x-go-name: Status
status_code:
example: 100
format: int64
type: integer
x-go-name: StatusCode
type:
example: async
type: string
x-go-name: Type
type: object
schemas:
ClusterPut:
properties:
cluster_address:
description: The address of the cluster you wish to join
example: 10.0.0.1:8443
type: string
x-go-name: ClusterAddress
cluster_certificate:
description: The expected certificate (X509 PEM encoded) for the cluster
example: X509 PEM certificate
type: string
x-go-name: ClusterCertificate
cluster_token:
description: The cluster join token for the cluster you're trying to join
example: blah
type: string
x-go-name: ClusterToken
enabled:
description: Whether clustering is enabled
example: true
type: boolean
x-go-name: Enabled
member_config:
description: List of member configuration keys (used during join)
example: []
items:
$ref: '#/components/schemas/ClusterMemberConfigKey'
type: array
x-go-name: MemberConfig
server_address:
description: The local address to use for cluster communication
example: 10.0.0.2:8443
type: string
x-go-name: ServerAddress
server_name:
description: Name of the cluster member answering the request
example: server01
type: string
x-go-name: ServerName
title: ClusterPut represents the fields required to bootstrap or join a cluster.
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
StatusCode:
format: int64
title: StatusCode represents a valid operation and container status.
type: integer
x-go-package: github.com/lxc/incus/v7/shared/api
ClusterMember:
properties:
architecture:
description: The primary architecture of the cluster member
example: x86_64
type: string
x-go-name: Architecture
config:
description: Additional configuration information
example:
scheduler.instance: all
type: object
x-go-name: Config
database:
description: Whether the cluster member is a database server
example: true
type: boolean
x-go-name: Database
description:
description: Cluster member description
example: AMD Epyc 32c/64t
type: string
x-go-name: Description
failure_domain:
description: Name of the failure domain for this cluster member
example: rack1
type: string
x-go-name: FailureDomain
groups:
description: List of cluster groups this member belongs to
example:
- group1
- group2
items:
type: string
type: array
x-go-name: Groups
message:
description: Additional status information
example: fully operational
type: string
x-go-name: Message
roles:
description: List of roles held by this cluster member
example:
- database
items:
type: string
type: array
x-go-name: Roles
server_name:
description: Name of the cluster member
example: server01
type: string
x-go-name: ServerName
status:
description: Current status
example: Online
type: string
x-go-name: Status
url:
description: URL at which the cluster member can be reached
example: https://10.0.0.1:8443
type: string
x-go-name: URL
title: ClusterMember represents a member of a cluster.
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ClusterMemberStatePost:
properties:
action:
description: The action to be performed. Valid actions are "evacuate" and "restore".
example: evacuate
type: string
x-go-name: Action
mode:
description: Override the configured evacuation mode.
example: stop
type: string
x-go-name: Mode
title: ClusterMemberStatePost represents the fields required to evacuate a cluster member.
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ClusterMemberPut:
description: ClusterMemberPut represents the modifiable fields of a cluster member
properties:
config:
description: Additional configuration information
example:
scheduler.instance: all
type: object
x-go-name: Config
description:
description: Cluster member description
example: AMD Epyc 32c/64t
type: string
x-go-name: Description
failure_domain:
description: Name of the failure domain for this cluster member
example: rack1
type: string
x-go-name: FailureDomain
groups:
description: List of cluster groups this member belongs to
example:
- group1
- group2
items:
type: string
type: array
x-go-name: Groups
roles:
description: List of roles held by this cluster member
example:
- database
items:
type: string
type: array
x-go-name: Roles
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
StoragePoolState:
properties:
inodes:
$ref: '#/components/schemas/ResourcesStoragePoolInodes'
space:
$ref: '#/components/schemas/ResourcesStoragePoolSpace'
title: StoragePoolState represents the state of a storage pool.
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ClusterMemberSysInfo:
properties:
buffered_ram:
format: uint64
type: integer
x-go-name: BufferRAM
free_ram:
format: uint64
type: integer
x-go-name: FreeRAM
free_swap:
format: uint64
type: integer
x-go-name: FreeSwap
load_averages:
items:
format: double
type: number
type: array
x-go-name: LoadAverages
processes:
format: uint16
type: integer
x-go-name: Processes
shared_ram:
format: uint64
type: integer
x-go-name: SharedRAM
total_ram:
format: uint64
type: integer
x-go-name: TotalRAM
total_swap:
format: uint64
type: integer
x-go-name: TotalSwap
uptime:
format: int64
type: integer
x-go-name: Uptime
title: ClusterMemberSysInfo represents the sysinfo of a cluster member.
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ClusterMemberState:
properties:
storage_pools:
additionalProperties:
$ref: '#/components/schemas/StoragePoolState'
type: object
x-go-name: StoragePools
sysinfo:
$ref: '#/components/schemas/ClusterMemberSysInfo'
title: ClusterMemberState represents the state of a cluster member.
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
Cluster:
properties:
enabled:
description: Whether clustering is enabled
example: true
type: boolean
x-go-name: Enabled
member_config:
description: List of member configuration keys (used during join)
example: []
items:
$ref: '#/components/schemas/ClusterMemberConfigKey'
type: array
x-go-name: MemberConfig
server_name:
description: Name of the cluster member answering the request
example: server01
type: string
x-go-name: ServerName
title: Cluster represents high-level information about a cluster.
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ClusterMembersPost:
properties:
server_name:
description: The name of the new cluster member
example: server02
type: string
x-go-name: ServerName
title: ClusterMembersPost represents the fields required to request a join token to add a member to the cluster.
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ClusterMemberPost:
properties:
server_name:
description: The new name of the cluster member
example: server02
type: string
x-go-name: ServerName
title: ClusterMemberPost represents the fields required to rename a cluster member.
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesStoragePoolInodes:
description: ResourcesStoragePoolInodes represents the inodes available to a given storage pool
properties:
total:
description: Total inodes
example: 30709993797
format: uint64
type: integer
x-go-name: Total
used:
description: Used inodes
example: 23937695
format: uint64
type: integer
x-go-name: Used
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ClusterCertificatePut:
description: ClusterCertificatePut represents the certificate and key pair for all cluster members
properties:
cluster_certificate:
description: The new certificate (X509 PEM encoded) for the cluster
example: X509 PEM certificate
type: string
x-go-name: ClusterCertificate
cluster_certificate_key:
description: The new certificate key (X509 PEM encoded) for the cluster
example: X509 PEM certificate key
type: string
x-go-name: ClusterCertificateKey
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
Operation:
description: Operation represents a background operation
properties:
class:
description: Type of operation (task, token or websocket)
example: websocket
type: string
x-go-name: Class
created_at:
description: Operation creation time
example: '2021-03-23T17:38:37.753398689-04:00'
format: date-time
type: string
x-go-name: CreatedAt
description:
description: Description of the operation
example: Executing command
type: string
x-go-name: Description
err:
description: Operation error message
example: Some error message
type: string
x-go-name: Err
id:
description: UUID of the operation
example: 6916c8a6-9b7d-4abd-90b3-aedfec7ec7da
type: string
x-go-name: ID
location:
description: What cluster member this record was found on
example: server01
type: string
x-go-name: Location
may_cancel:
description: Whether the operation can be canceled
example: false
type: boolean
x-go-name: MayCancel
metadata:
additionalProperties: {}
description: Operation specific metadata
example:
command:
- bash
environment:
HOME: /root
LANG: C.UTF-8
PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
TERM: xterm
USER: root
fds:
'0': da3046cf02c0116febf4ef3fe4eaecdf308e720c05e5a9c730ce1a6f15417f66
'1': 05896879d8692607bd6e4a09475667da3b5f6714418ab0ee0e5720b4c57f754b
interactive: true
type: object
x-go-name: Metadata
resources:
additionalProperties:
items:
type: string
type: array
description: Affected resources
example:
instances:
- /1.0/instances/foo
type: object
x-go-name: Resources
status:
description: Status name
example: Running
type: string
x-go-name: Status
status_code:
$ref: '#/components/schemas/StatusCode'
updated_at:
description: Operation last change
example: '2021-03-23T17:38:37.753398689-04:00'
format: date-time
type: string
x-go-name: UpdatedAt
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ResourcesStoragePoolSpace:
description: ResourcesStoragePoolSpace represents the space available to a given storage pool
properties:
total:
description: Total disk space (bytes)
example: 420100937728
format: uint64
type: integer
x-go-name: Total
used:
description: Used disk space (bytes)
example: 343537419776
format: uint64
type: integer
x-go-name: Used
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ClusterGroupsPost:
properties:
config:
description: Cluster group configuration map
example:
user.mykey: foo
type: object
x-go-name: Config
description:
description: The description of the cluster group
example: amd64 servers
type: string
x-go-name: Description
members:
description: List of members in this group
example:
- server01
- server02
items:
type: string
type: array
x-go-name: Members
name:
description: The new name of the cluster group
example: group1
type: string
x-go-name: Name
title: ClusterGroupsPost represents the fields available for a new cluster group.
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
ClusterMemberConfigKey:
description: 'The Value field is empty when getting clustering information with GET
1.0/cluster, and should be filled by the joining server when performing a PUT
1.0/cluster join request.'
properties:
description:
description: A human friendly description key
example: '"source" property for storage pool "local"'
type: string
x-go-name: Des
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/incus/refs/heads/main/openapi/incus-cluster-api-openapi.yml