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, manage Tailscale Serve templates, 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.

Tailscale Serve operations

tailscaleServeOverview returns typed templates, explicit per-agent assignments, Tailscale identities, desired-versus-observed state, and related AgentJob records. tailscaleServeOperation(id:) returns durable per-agent progress. Use expectedRevision when updating, toggling, or deleting a template, and always send explicit {agentId, enabled} assignments when upserting.

The inspect, upsert, toggle, and delete mutations return an operation immediately. Subscribe to tailscaleServeOverviewChanged for fleet updates or tailscaleServeOperationChanged(id:) for one operation; clients never need to parse an agent job’s JSON result. See Tailscale Serve for validation and lifecycle behavior.

App and repository transfers

repositoryTransferExportPreview(input:) lists selectable settings, definitions, and dependencies; exportRepositoryTransfer(input:) returns the selected portable package. previewRepositoryTransfer(input:) resolves matches and mappings, inspects selected clone destinations, and returns conflicts plus a fingerprint. Submit the same input and fingerprint to applyRepositoryTransfer, with a stable requestId for retries of that exact request.

Configuration is saved atomically before independent clone jobs run. Read repositoryTransferOperation(id:) or subscribe to repositoryTransferChanged(operationId:) for per-checkout results. retryRepositoryTransfer retries failed checkouts without applying the configuration again. appRepositorySync and syncAppRepositories provide app-wide clone coverage and dispatch. These operations reject enrolled agent credentials; use a user session or API key.

See Import and export for selection behavior, paused automations, destination validation, and sensitive package contents.

Crashes and dSYMs

crashReports(filter:, first:, after:) pages crash reports newest first, and crashReport(id:) returns one with its symbolicated threads, binaryImages, missingImages, attachedDsyms, and similarCrashes. Frame fields such as symbol, sourceFile, sourceLine, and inlined already include what the dSYMs added, and symbolicatedText renders the whole report in Apple’s text format. dsyms and dsym(id:) list the indexed dSYMs with their slices and crashes; dsymUploads lists uploads still in progress or failed.

symbolicateCrashReport starts a fresh symbolication, updateDsymUpload changes an upload’s project, build ID, and link, and updateCrashSettings changes collection, the symbolication agent, and retention. Uploading files happens over REST — see Crashes and dSYMs. Subscribe to crashReportsChanged and dsymsChanged for live updates.

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.