API Reference

Queries

All read operations available in the flex.plane GraphQL API, grouped by domain.

All queries are read-only operations. They never modify state. This page lists every query in the schema, organized by domain.

Virtual Machines

Queries for fetching VM details, metrics, backups, snapshots, firewall rules, and file system contents.

`vm(vmId: ID!): VM`

Returns a single VM by its ID. Includes status, resource allocation, network interfaces, and attached disks.

Role: VDC_USER

{
  vm(vmId: "em9uZS1hOm5vZGUwMToxMDA=") {
    id
    name
    status
    cpus
    memory
    uptime
    host
    zone
    networks { network ipv4 mac }
    disks { id size storage boot }
    agent { running }
  }
}

`vms(network: ID): [VM!]`

Returns all VMs visible in the current context. Optionally filter by network ID to list only VMs attached to a specific network.

Role: VDC_USER

{ vms { id name status cpus memory host zone } }

# Filter by network
{ vms(network: "prod-net") { id name status } }

`vmBackups(vmId: ID!): [VMBackup!]`

Lists all backups for a specific VM.

Role: VDC_USER | Returns: backup ID, name, timestamp, and size.

`vmSnapshots(vmId: ID!): [VMSnapshot!]`

Lists all snapshots for a specific VM, including their parent relationships.

Role: VDC_USER | Returns: snapshot ID, description, date, and parent snapshot ID.

`vmMetrics(vmId: ID!, timeframe: String!): [VMMetrics!]!`

Returns time-series metrics for a VM. The timeframe parameter controls the time range (e.g., "hour", "day", "week").

Role: VDC_USER | Returns: CPU usage, memory usage, network I/O, and disk I/O over time.

`vmFiles(vmId: ID!, path: String!): [FileEntry!]!`

Lists files and directories at the given path inside a VM. Requires the QEMU guest agent to be running.

Role: USER | Returns: file name, path, type (FILE/DIRECTORY/SYMLINK), size, permissions, owner, group, and modification time.

`vmFileContent(vmId: ID!, path: String!): String!`

Reads the content of a file inside a VM. Requires the QEMU guest agent.

Role: USER

`vmFirewallRules(vmId: ID!): [FirewallRule!]!`

Returns the firewall rules configured on a VM.

Role: VDC_USER | Returns: position, action (ACCEPT/DROP/REJECT), direction (IN/OUT), protocol, destination port, source, comment, and enabled state.

`vmFirewallOptions(vmId: ID!): FirewallOptions!`

Returns the firewall configuration for a VM: whether the firewall is enabled and the default policies for inbound and outbound traffic.

Role: VDC_USER

Networking

`networks: [Network!]`

Lists all networks in the current context.

Role: VDC_USER | Returns: network ID, name, IP range, and gateway.

{ networks { id name ipRange gateway } }

{
  kubernetesCluster(id: "my-cluster") {
    id
    name
    version
    state { status reason }
    controlPlane { version endpoints state { status } }
    nodePools {
      id
      size
      region
      zone
      readyReplicas
      nodes { id name version state { status } }
    }
    nodeNetwork { id name ipRange }
    createdAt
  }
}

{
  zones {
    id
    name
    hosts { id name ipAddress status }
    resources {
      cpu { cores percentage }
      memory { used total percentage }
      storage { used total percentage }
    }
  }
}

{
  statistics {
    hosts { total online }
    virtualMachines { total running }
    networks { total }
    zones { total }
  }
}

Configuration

`computeProfiles: [ComputeProfile!]!`

Lists all compute profiles (CPU/memory sizing templates).

Role: VDC_USER | Returns: profile ID, name, CPU count, and memory in MiB.

`storageProfiles: [StorageProfile!]!`

Lists all storage profiles with their zone-to-storage-pool mappings and I/O limits.

Role: VDC_USER

`vmImages: [VMImage!]`

Lists all available OS images in the catalog.

Role: VDC_USER | Returns: image ID, name, version, download URL, and checksum file URL.

`defaultStorage: DefaultStorage!`

Returns the default storage pool assignments for backups, VMs, images, and ISOs.

Role: USER

`backupStoragePools: [StoragePool!]`

Lists storage pools available for VM backups.

Role: USER

`vmStoragePools: [StoragePool!]`

Lists storage pools available for VM disks.

Role: USER

`imageStoragePools: [StoragePool!]`

Lists storage pools available for OS image storage.

Role: USER

`isoStoragePools: [StoragePool!]`

Lists storage pools available for ISO file storage.

Role: USER

Organization

`virtualDatacenters: [VirtualDatacenter!]!`

Lists all VDCs visible to the current user.

Role: ANONYMOUS

`virtualDatacenter(id: ID!): VirtualDatacenter`

Returns a specific VDC by ID with its quota configuration.

Role: VDC_USER

`members: [Member!]!`

Lists all members of the current VDC with their roles.

Role: VDC_ADMIN

`users: [UserInfo!]!`

Lists all users in the tenant. Useful for finding user IDs when adding VDC members.

Role: VDC_ADMIN

`auditLog(filter: AuditFilter): [AuditEvent!]`

Returns the audit log for the current context. Optionally filter by zone, host, or VM.

Role: VDC_USER

{
  auditLog(filter: { zoneId: "zone-a" }) {
    id
    description
    status
    user
    start
    end
    target
    zone
  }
}

`tenant: Tenant!`

Returns tenant information including name, domain, available roles, and the current flex.plane version.

Role: ANONYMOUS

`context: Context!`

Returns the authenticated user's context: their ID, display name, and active roles.

Role: ANONYMOUS

Edit this pageorReport an issue

VDC Scoping

How to scope API requests to a specific Virtual Datacenter using the FlexPlane-VDC-ID header.

Mutations

All write operations available in the flex.plane GraphQL API, grouped by domain.