Skip to main content

GraphQL API (backend)

The Vibecontrols backend (the Vibecontrols backend) is a GraphQL surface inside Burdenoff Workspaces. You query it via the workspaces gateway.

What you'll learn​

  • The endpoint
  • Auth headers
  • Key types
  • How to discover the live schema

Endpoint​

https://graphqlworkspaces.burdenoff.com/workspaces/graphql

(Or your tenant's equivalent if self-hosted.)

Auth​

Standard Burdenoff Workspaces auth — see platform auth for full detail. Short version:

Authorization: Bearer <token>
x-workspace-id: <workspace-uuid>

x-workspace-id is REQUIRED. Vibecontrols data is workspace-scoped.

Key types (Vibecontrols-specific)​

These are the major models exposed via federation:

TypeWhat
AgentA connected agent (hostname, platform, version, isActive, lastHeartbeat, tunnelUrl)
TargetA connection destination (DIRECT, SSH, RDP, VNC)
VibeA project context (type, status, path, gitBranch, environmentVariables)
SessionA live terminal session (type, status, ttydUrl, accumulatedSeconds)
VibeDeckAn action-button grid (gridColumns, gridRows, buttonSize, colorTheme)
VibeDeckButtonA single button (row, column, actionType, command/script/webhookUrl)
VibeDeckShareLinkToken-based share for a VibeDeck
SessionShareDirect share of a session with a user
SessionShareLinkToken-based session share
SessionCollaboratorActive participant on a shared session
NoteMarkdown attached to a vibe
AiPromptReusable prompt template
ConfigurationScoped key-value config
WebhookOutbound HTTP delivery config
AiToolEventTelemetry from external AI tools
Action / ActionExecutionReusable command/script/webhook + its runs

Example queries​

query MyAgents {
  myAgents {
    id
    name
    hostname
    platform
    isActive
    lastHeartbeat
    tunnelUrl
  }
}

query VibeWithSessions($vibeId: ID!) {
  vibe(id: $vibeId) {
    id
    name
    type
    status
    path
    environmentVariables
    sessions {
      id
      name
      type
      status
      ttydUrl
    }
  }
}

Example mutations​

mutation CreateVibe {
  createVibe(input: {
    name: "my-api"
    path: "/home/me/code/my-api"
    type: REPOSITORY
  }) { id }
}

mutation CreateSession {
  createSession(input: {
    vibeId: "..."
    agentId: "..."
    type: TMUX
    name: "dev"
  }) { id ttydUrl }
}

mutation RotateAgentApiKey($agentId: ID!) {
  rotateAgentApiKey(agentId: $agentId) { newKey }
}

Subscriptions​

subscription AgentHealth($agentId: ID!) {
  agentHealth(agentId: $agentId) {
    isActive
    lastHeartbeat
  }
}

subscription SessionOutput($sessionId: ID!) {
  sessionOutput(sessionId: $sessionId) {
    chunk
    timestamp
  }
}

WebSocket transport via graphql-ws at the same URL with wss://.

Discover the live schema​

The composed live API schema is published to the schema registry as the live registry. Browse there for the authoritative schema with every field, type, and @rbac directive.

Locally: the agent's REST API does NOT expose this — it's only on the backend.

Next steps​