GraphQL API

Complete GraphQL API reference for Infinibay - queries, mutations, types, and schema

GraphQL API

GraphQL API for Infinibay VDI platform. Apollo Server 4 + TypeGraphQL 2. 50+ queries, 40+ mutations. Real-time updates via Socket.io.

Endpoint

http://localhost:4000/graphql (HTTP POST, application/json, JWT in Authorization: Bearer <token>)

Authentication

See authentication.md for details. Login mutation returns JWT token. Include in header for all requests.

Type System

Scalars: ID, String, Int, Float, Boolean, DateTime (ISO 8601), JSON Enums: UserRole (USER/ADMIN/SUPER_ADMIN), MachineStatus (RUNNING/STOPPED/PAUSED/SUSPENDED), etc.

Queries

User

  • currentUser: Get authenticated user
  • user(id): Get specific user (ADMIN)
  • users: List all users (ADMIN)

Machine (VM)

  • machine(id): Get VM by ID
  • machines(filter, pagination): List VMs with filtering
  • machineConfiguration(id): Get VM hardware config
  • vmStatistics(id): Get VM stats

Department

  • department(id): Get department
  • departments: List departments
  • departmentMembers(id): List department members

Health & Monitoring

  • healthSnapshots(vmId, filter): VM health history
  • recommendations(vmId): Automated recommendations
  • systemMetrics(vmId, timeRange): System metrics

Firewall

  • firewallRuleSets(vmId): Get firewall rules
  • effectiveFirewallRules(vmId): Computed effective rules
  • servicePresets: Available service presets
  • blockedConnections(vmId): Recent blocked traffic

Maintenance

  • maintenanceTasks(vmId, filter): Scheduled tasks
  • maintenanceHistory(vmId): Task execution history

Templates & ISOs

  • machineTemplates(filter): VM templates
  • isos(filter): Available ISOs
  • osAvailability: Supported operating systems

Applications

  • applications(filter): Application catalog
  • machineApplications(vmId): Installed apps on VM
  • applicationUsage(vmId, appId): App usage stats

Network & Snapshots

  • networks: Libvirt networks
  • snapshots(vmId): VM snapshots
  • packages(vmId, search): Guest OS packages

Mutations

User Management

  • login(email, password): Authenticate user
  • createUser(data): Create user (ADMIN)
  • updateUser(id, data): Update user
  • deleteUser(id): Delete user (ADMIN)
  • changePassword(currentPassword, newPassword): Change own password

VM Lifecycle

  • createMachine(data): Create VM
  • updateMachine(id, data): Update VM config
  • deleteMachine(id): Delete VM
  • startMachine(id): Start VM
  • stopMachine(id): Stop VM
  • restartMachine(id): Restart VM
  • pauseMachine(id): Pause VM
  • resumeMachine(id): Resume VM

VM Configuration

  • updateMachineConfiguration(id, data): Update hardware
  • attachISO(vmId, isoId): Attach ISO
  • detachISO(vmId): Detach ISO

Firewall

  • createFirewallRule(input): Create firewall rule
  • updateFirewallRule(id, input): Update rule
  • deleteFirewallRule(id): Delete rule
  • toggleServicePreset(vmId, presetId, enabled): Enable/disable service preset
  • applyFirewallTemplate(vmId, templateId): Apply template

Health & Maintenance

  • scheduleHealthCheck(vmId, type): Schedule health check
  • scheduleMaintenanceTask(vmId, data): Schedule maintenance
  • executeMaintenanceTask(id): Execute task immediately
  • cancelMaintenanceTask(id): Cancel scheduled task

Snapshots

  • createSnapshot(vmId, name, description): Create VM snapshot
  • restoreSnapshot(snapshotId): Restore snapshot
  • deleteSnapshot(snapshotId): Delete snapshot

Applications

  • installApplication(vmId, appId): Install app on VM
  • uninstallApplication(vmId, appId): Uninstall app
  • updateApplication(id, data): Update app metadata

Packages (Guest OS)

  • installPackage(vmId, packageName): Install package
  • removePackage(vmId, packageName): Remove package
  • updatePackages(vmId, packageNames): Update packages

Department

  • createDepartment(name, description): Create department
  • updateDepartment(id, data): Update department
  • deleteDepartment(id): Delete department

Templates

  • createMachineTemplate(data): Create VM template
  • updateMachineTemplate(id, data): Update template
  • deleteMachineTemplate(id): Delete template

Common Input Types

CreateMachineInput: name, departmentId, templateId, cpus, memoryMB, diskGB, osType UpdateMachineInput: name, description, cpus, memoryMB CreateFirewallRuleInput: action (ACCEPT/DROP), direction (INBOUND/OUTBOUND), protocol (TCP/UDP/ICMP), srcIP, destIP, srcPort, destPort MaintenanceTaskInput: type (DISK_CLEANUP/DEFRAG/WINDOWS_UPDATE/DEFENDER_SCAN), schedule, priority

Error Handling

Error codes: UNAUTHORIZED (auth failure), FORBIDDEN (insufficient permissions), BAD_USER_INPUT (validation error), NOT_FOUND (resource not found).

See authentication.md for detailed error handling.

Pagination

Queries support skip and take parameters for pagination:

machines(skip: 0, take: 20)

Filtering

Queries support filtering via where parameter:

machines(where: { status: RUNNING, departmentId: "dept-123" })

Real-Time Updates

GraphQL API does not use subscriptions. Real-time updates delivered via Socket.io. See architecture.md for Socket.io details.

Schema Generation

Schema generated from TypeGraphQL decorators, emitted to backend/app/schema.graphql. Frontend codegen uses this schema.

For detailed authentication flow, see authentication.md. For architectural details, see architecture.md.

Previous
CPU Pinning & NUMA Topology
Next
Authentication System