GraphQL API Overview

flex.plane exposes a single GraphQL API that powers both the portal UI and any custom integrations you build. Every operation available in the portal is available through the API. There are no hidden REST endpoints or backdoors.

Access the API

The GraphQL endpoint is served by the orchestrator at:

POST https://<your-domain>/graphql

All requests are standard HTTP POST with a JSON body containing your GraphQL query or mutation:

curl -X POST https://flexplane.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{"query": "{ tenant { name version } }"}'

The API accepts two optional headers beyond Authorization:

Understand the schema

The schema is organized by domain. Each domain (VMs, networking, Kubernetes, etc.) extends the root Query and Mutation types with its own fields. This keeps the schema modular while presenting a single, unified API surface.

Key structural elements:

• Queries are read operations. They fetch VMs, networks, zones, clusters, and configuration.
• Mutations are write operations. They create, modify, and delete resources.
• Custom scalars extend the type system with Time (ISO 8601), Duration (Go-style like "2h30m"), Int64 (64-bit integers), and Map (arbitrary key-value pairs).
• Directives enforce authorization (@hasRole) and input validation (@constraint).
• Enums define fixed value sets for roles, statuses, firewall actions, and more.

A simplified view of how the schema is split:

schema.graphqls       -- base types, directives, scalars, Role enum
vm.graphqls           -- VM queries, mutations, types
network.graphqls      -- network queries, mutations, types
kubernetes.graphqls   -- Kubernetes cluster operations
zone.graphqls         -- zone and host queries
vdc.graphqls          -- Virtual Datacenter management
firewall.graphqls     -- VM-level firewall rules
gateway.graphqls      -- edge gateway and gateway firewall
loadbalancer.graphqls -- load balancer operations
storage.graphqls      -- storage pools and profiles
compute.graphqls      -- compute profiles
catalog.graphqls      -- VM image catalog
member.graphqls       -- VDC member management
audit.graphqls        -- audit log queries
context.graphqls      -- tenant and user context
statistic.graphqls    -- system-wide statistics
filesystem.graphqls   -- VM file system access

Use the playground

The orchestrator ships with an interactive GraphQL playground at:

https://<your-domain>/playground

The playground lets you explore the full schema, write queries with autocompletion, and execute them against your live environment. It is the fastest way to learn the API.

To authenticate in the playground, add your Bearer token in the HTTP Headers panel at the bottom:

{
  "Authorization": "Bearer eyJhbGciOiJSUzI1...",
  "FlexPlane-VDC-ID": "my-vdc"
}

A good first query to verify your setup:

{
  tenant {
    name
    domain
    version
  }
  context {
    id
    name
    roles
  }
}

This returns your tenant info and your current user context, confirming that authentication and the API connection both work.