> ## Documentation Index
> Fetch the complete documentation index at: https://ai-development-environment.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/reference/development) for the environment variables that move those ports.

<Warning>
  `/api/graphql` must stay authenticated. Do not add it to a Cloudflare Access
  bypass — see [Hosting](/reference/hosting).
</Warning>

## 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](/reference/authentication) for the route matrix and [API keys](/system/api-keys) to create a credential.

## Apollo Studio

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

<Card title="ai-development-environment on Apollo Studio" icon="rocket" href="https://studio.apollographql.com/public/ai-development-environment/variant/current">
  Browse the schema, search types and fields, and read the generated docs
  without running the control plane.
</Card>

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:

```graphql theme={null}
query Health {
  health
}
```

```bash theme={null}
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.

```graphql theme={null}
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:

```graphql theme={null}
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](https://studio.apollographql.com/public/ai-development-environment/variant/current) or the Apollo sandbox at `/api/graphql`.

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

```graphql theme={null}
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](/reference/api).