GraphQL API

Endpoint, authentication, subscriptions, and how to read the generated schema reference.

The control plane exposes a single GraphQL endpoint that backs the entire dashboard. Every page in the app — Action Center, agents, builds, Plans and Sessions, workflows — reads and writes through it, so anything the UI can do is available to a script or an external client.

The Queries, Mutations, and Types sections in this tab are generated directly from the shipped schema, so they always match the SDL the server serves.

Endpoint

Purpose	Address
GraphQL over HTTP	POST /api/graphql
Agent WebSocket (Homebrew service)	ws://127.0.0.1:3091/graphql
Agent WebSocket (development)	ws://127.0.0.1:3092/graphql

An Apollo Server (Federation subgraph) is mounted at /api/graphql through a Next.js route handler. Outside production — or when APOLLO_SANDBOX=true — introspection and the Apollo sandbox are enabled, so opening /api/graphql in a browser lets you explore the schema interactively.

Control agents on managed machines connect outbound to the WebSocket port and never expose a listening port of their own. See Development for the environment variables that move those ports.

/api/graphql must stay authenticated. Do not add it to a Cloudflare Access bypass — see Hosting.

Authentication

GraphQL accepts one credential per request:

Client	Credential
Dashboard	Better Auth session cookie
iOS or another native client	Authorization: Bearer <session-token>
Script or MCP client	X-API-Key: aide_...
Enrolled agent	Authorization: Bearer agent_...

The same header names can be sent as WebSocket connection parameters. API keys have full GraphQL access, but cannot access the dashboard or user-management REST routes. Agent tokens retain their restricted operations.

Anonymous execution is rejected before GraphQL resolution. The only exception is one exact enrollAgent mutation carrying a valid one-time enroll_ token. Introspection, aliases, batches, and mixed operations do not qualify.

See Authentication for the route matrix and API keys to create a credential.

Apollo Studio

The published schema is also available as a public graph in Apollo Studio:

ai-development-environment on Apollo Studio

Browse the schema, search types and fields, and read the generated docs without running the control plane.

Studio is the easiest way to explore the graph when you do not have a local server: it covers every root type — including subscriptions, which the generated sidebar here omits — and its Explorer builds and formats operations for you. To run those operations, point Explorer at your own /api/graphql endpoint and supply the usual authentication; the public graph itself is schema-only.

Check connectivity

The health query verifies database connectivity. It returns "ok" when the database is reachable and "degraded" otherwise:

query Health {
  health
}

curl -s http://127.0.0.1:3090/api/graphql \
  -H "X-API-Key: aide_replace-with-created-key" \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ health }"}'

Queries and mutations

Queries read control-plane state: agents and their jobs, codebases and worktrees, builds and build logs, AI Plans, Sessions and runs, workflows, commands, skills, GitHub and Jira caches, devices, signing assets, and settings.

Mutations drive the same objects: enroll and configure agents, start and cancel builds, create worktrees, launch AI runs, answer run questions, edit and run workflows and commands, sync skills, and update settings.

query Agents {
  agents {
    id
    name
    hostname
    connectionStatus
    lastSeenAt
  }
}

Arguments, return types, deprecations, and a sample response are listed on each generated operation page. Open Queries or Mutations in the generated GraphQL navigation and select agents or enrollAgent. Field types link through to the Types section, so you can walk the graph from any operation.

Worktree admission queues

worktreeRunQueue returns the effective queued order for one worktree or the queued entries associated with one workflow. A worktree query combines workflow runs, Plans, and Sessions:

query WorktreeQueue($worktreeId: ID!) {
  worktreeRunQueue(worktreeId: $worktreeId) {
    position
    id
    kind
    displayNumber
    status
    phase
    queuedAt
    exclusiveWorktree
    worktreeConcurrencyLimit
  }
}

RunConfigurationInput.worktreeConcurrencyLimit controls same-kind admission on a worktree. Omit it for the kind default: 0 for unlimited Plans or 1 for Sessions. Supply 0 for unlimited concurrency or an integer from 1 through 32 for a finite limit. playPlan exposes the same option for the Session it creates.

Set CreateWorkflowInput.exclusiveWorktree or SaveWorkflowDraftInput.exclusiveWorktree to make each top-level run reserve its resolved worktree. The default is false. A queued WorkflowRun also exposes its effective queue; that field becomes empty after admission.

overlapScope on the same two inputs picks the set of runs overlapPolicy is measured against: WORKTREE, the default, keeps a queue per worktree so worktrees never wait on each other, and GLOBAL counts every run of the workflow. Runs with no worktree share one queue under WORKTREE.

Subscriptions

The schema also defines subscriptions, which power the dashboard’s live output — job and build logs, run events, Action Center changes, and status updates. Mintlify generates pages for Query and Mutation fields only, so subscriptions do not appear in the sidebar. Their payloads do: each one resolves to a documented type, such as BuildLogChunk. For the full subscription list, use Apollo Studio or the Apollo sandbox at /api/graphql.

Log chunks arrive Base64-encoded, with a sequence number for ordering:

subscription BuildLogs($buildId: ID!) {
  buildLogChunkAdded(buildId: $buildId) {
    sequence
    stream
    dataBase64
  }
}

Related endpoints

Read-only codebase data over REST and the Streamable HTTP MCP endpoint are documented in APIs.