Skip to main content

GraphQL API (backend)

Everything the Vibecontrols web app and CLI can do is available to you through a GraphQL API on the Burdenoff Workspaces platform. Every operation is authenticated and permission-checked against the calling user's role in the workspace.

What you'll learn​

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

Endpoint​

VibeControls is a workspace product. The GraphQL endpoint is workspace-scoped:

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

Environment selection​

The endpoint defaults to production. Select a different environment by changing the URL:

EnvironmentWorkspace endpointGlobal endpoint
prod (default)https://graphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://graphql.burdenoff.com/global/graphql
alphahttps://alphagraphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://alphagraphql.burdenoff.com/global/graphql
localhttp://localhost:4003/workspaces/graphqlhttp://localhost:4000/global/graphql

If you use the Node SDK or Python SDK, pass the endpoint in config. If you use the CLI, set BURDENOFF_ENV=local|alpha|prod (default prod).

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 the API exposes:

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​

Introspection is disabled on the public endpoint. The authoritative schema — every type, field, and argument — is published in the Burdenoff Workspaces developer docs; the types above cover the Vibecontrols-specific part of it.

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

Next steps​