APIs

The GraphQL API, the REST endpoints, the OpenAPI contract, and the Streamable HTTP MCP endpoint.

The control plane exposes three programmable surfaces, all of them thin adapters over the same server-side services. Anything the dashboard can do, a script can do too.

Surface	Endpoint	Use it for
GraphQL	POST /api/graphql, plus a WebSocket for subscriptions	Everything. This is what the dashboard itself uses
REST	/api/codebases, /api/telemetry/*, /api/public/crashes, /api/dsyms, /api/ios/apns-devices	Narrow integrations with route-specific security
MCP	/api/mcp	Giving an AI client a scoped set of tools

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.

The SDL lives in schemas/**/*.graphql, one file per domain, and is bundled into the app by scripts/prebuild-schema.ts. Resolvers are dependency-injected factories under src/graphql/resolvers/.

Subscriptions are served over a separate WebSocket listener rather than the HTTP route:

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

Browser clients authenticate with a Better Auth cookie. Native clients and enrolled agents send their bearer credential in the authorization connection parameter. API clients send X-API-Key as a header or connection parameter. The server resolves exactly one typed principal — user, API key, or agent — before execution. The app also rewrites /graphql on the HTTP origin to the WebSocket listener, so a browser and a reverse proxy can reach subscriptions on a single origin.

Every query, mutation, and type is documented in the GraphQL API tab, generated from that schema.

Build clients use buildRunAgents(buildId:) to discover eligible target Macs, optionally pass agentId to inspectBuildRunDestinations, and pass targetAgentId with RunBuildInput. Omitting either agent field preserves the original build-agent behavior. Deployment results expose the target agent and optional artifact-transfer status and progress.

Shared server URLs

ServerUrlKind is LOCAL, REMOTE, or PROXY. Use serverUrlSettings to read detected and effective origins, overrides, Proxy, and defaults; saveServerUrlSettings saves them; serverUrlSettingsChanged notifies clients to refetch. Telemetry override fields remain deprecated delegates to this shared service.

StartBuildInput.serverUrlKind is optional. Builds and coverage builds snapshot the resolved bases and choice; rebuilds retain the kind and resolve current settings. buildArtifactLinks returns signed download and selected manifest URLs. Device enrollment and OTA routes carry serverUrlKind through follow-up URLs, resolved server-side against configured settings.

SSE responses include endpointPath, localUrl, remoteUrl, and nullable proxyUrl; publicUrl remains for compatibility. See Server URLs and the script contract.

MCP catalog and preset portability

The web and iOS apps use the same GraphQL operations to export tool definitions, share presets, and review imports:

Operation	Purpose
exportMcpToolCatalog(format:, source:, groupIds:)	Export Markdown or JSON tool definitions plus a preset-generation contract. source is ALL (default), BUILTIN, or EXTERNAL; omit groupIds to include all groups from those sources.
exportMcpToolPresets(ids:)	Export the selected presets in portable JSON.
previewMcpToolPresetImport(input:)	Validate a document, per-preset decisions, and external-server mappings without saving.
importMcpToolPresets(input:, previewToken:)	Revalidate and atomically apply a reviewed import.
mcpToolPresets(kind:)	List local preset IDs and metadata, optionally filtered to PLAN or SESSION.

Exports return filename, contentType, and the document’s content. Catalog exports can be partial when an external server cannot be discovered; check the exported availability information before using them as an inventory.

query ExportMcpCatalog {
  exportMcpToolCatalog(format: JSON, source: ALL) {
    filename
    contentType
    content
  }
}

Preset membership is source-qualified. The authoritative McpToolPreset.tools field contains { source, name, serverId, serverName }. Built-ins use source: BUILTIN and their ordinary name; external references use source: EXTERNAL, a local serverId, and the raw upstream tool name. The legacy toolNames output contains only built-in names.

Use McpToolPresetInput.tools for complete mixed membership. Do not send it together with toolNames. Older clients can continue editing built-in-only presets with toolNames. A legacy update to a mixed preset is rejected with an upgrade message so external selections cannot be lost.

Portable documents use format: "aide.mcp-presets.export", schemaVersion: 1, and an array of presets. External selections use a document-local serverKey, not a local server ID or an advertised MCP alias. See the portable JSON example. Documents are limited to 2 MiB and 100 presets.

McpToolPresetImportInput.document is the JSON document serialized as a string. Optional decisions contain an entry index, an action (CREATE, REPLACE, or SKIP), and optional name and targetId. Optional serverMappings associate { serverKey, serverId } with an already configured external server. Import never creates servers or credentials.

query ReviewMcpPresetImport($input: McpToolPresetImportInput!) {
  previewMcpToolPresetImport(input: $input) {
    token
    canImport
    errors
    entries {
      index
      name
      action
      targetId
      toolCount
      errors
      warnings
    }
    externalServers {
      key
      name
      transport
      selectedServerId
      suggestedServerId
      candidates {
        id
        name
        transport
      }
    }
  }
}

After resolving errors and reviewing the choices, send the same input with the preview’s token as previewToken:

mutation ApplyMcpPresetImport(
  $input: McpToolPresetImportInput!
  $previewToken: String!
) {
  importMcpToolPresets(input: $input, previewToken: $previewToken) {
    id
    name
    tools {
      source
      name
      serverId
      serverName
    }
  }
}

Changing the document or decisions requires a fresh preview. The server also rechecks referenced tools and replacement targets before writing; a changed or invalid review fails without a partial import. REPLACE keeps the target preset’s ID.

Agent build-transfer routes

Cross-agent app deployment uses REST routes under /api/agent/build-artifact-transfers/{transferId}. They support transfer status and metadata, HEAD offset inspection, sequential PATCH upload chunks, completion, and ranged download. These endpoints accept only the enrolled source or target agent assigned to that transfer; browser sessions and general API keys cannot substitute for that identity. Their payloads are intentionally small or ranged so reverse proxies never receive a whole large .app archive in one request.

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

{
  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 }"}'

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

REST endpoints

Codebases

Read-only access to the codebase checkouts registered across every enrolled agent.

These endpoints require a Better Auth session. API keys and agent credentials are not accepted.

Endpoint	Returns
GET /api/codebases	{ "codebases": [...] } — every registered checkout.
GET /api/codebases/by-path?path=/absolute/folder	{ "codebase": {...} } — one checkout resolved by its exact path.

curl -s 'http://127.0.0.1:3090/api/codebases/by-path?path=/Users/me/src/acme'

Each record carries the checkout’s Git state and the agent it lives on: id, path, observedOrigin, branch, headSha, upstream, ahead, behind, syncState, availability, statusError, the lastCheckedAt / lastFetchedAt timestamps, an optional branch listing, plus nested repository, agent, and activeJob objects.

Errors use a consistent envelope — { "error": { "code", "message" } }:

Status	Code	Cause
400	INVALID_PATH	The path parameter is missing or empty
404	CODEBASE_NOT_FOUND	No registered checkout uses that path
409	AMBIGUOUS_PATH	Two agents use the same path; the response adds a matches array naming them
500	INTERNAL_ERROR	Unexpected server error

AMBIGUOUS_PATH is common when the same repository is checked out at the same location on more than one Mac. Use the matches array to pick an agent, then look the codebase up by id over GraphQL or MCP.

Telemetry ingestion

Applications under test post their own logs and analytics events here. These endpoints are unauthenticated by design — they are meant to be reachable from a device or simulator.

Endpoint	Collects
POST /api/telemetry/console-logs	Console log records — see Console logs
POST /api/telemetry/analytics-events	Analytics events — see Analytics events
POST /api/telemetry/export	Renders a saved telemetry query as CSV, Markdown, or PDF; requires a session

Both ingestion endpoints accept either a single record or an atomic { "items": [...] } batch of at most 500 records, with the request body capped at 2 MiB.

Status	Meaning
201	Records collected
202	The payload was valid but collection is currently disabled
400	The payload failed validation
413	The body exceeded 2 MiB
415	Content-Type was not JSON

A 202 is not a failure. It means the server understood the payload and deliberately dropped it because collection is turned off, so a client can keep posting without special-casing the disabled state.

The export endpoint caps its request body at 256 KiB and returns PAYLOAD_TOO_LARGE beyond that. Direct export calls may omit locale and timeZone. When supplied, locale must be one of the dashboard’s supported locales and timeZone must be a valid IANA time-zone identifier; unrecognized values return 400 instead of reaching the formatter.

Crash and dSYM uploads

Apps post crash reports and CI posts debug symbols here. See Crashes and dSYMs for full examples. GitHub Actions workflows can use the Upload dSYMs action, which runs the resumable upload.

Endpoint	Credential	Accepts
POST /api/public/crashes	None required; X-API-Key or a session is recorded when sent	One .ips, .crash, or MetricKit JSON report as the raw body, up to 5 MiB after optional gzip decoding
POST /api/dsyms	X-API-Key or a session	A zip of .dSYM bundles as the file part of multipart/form-data, or a raw application/zip body, with optional projectName, buildId, and url; up to DSYM_UPLOAD_MAX_BYTES (2 GiB by default)
POST /api/dsyms/uploads	X-API-Key or a session	Starts a resumable upload of up to 20 GiB
HEAD / PATCH /api/dsyms/uploads/{id}	The credential that started it	Reports or appends at Upload-Offset, 16 MiB per chunk
POST /api/dsyms/uploads/{id}/complete	The credential that started it	Verifies the optional sha256 and indexes the zip
GET /api/crash-files/reports/{id}	X-API-Key or a session	The original report, or ?variant=symbolicated for the symbolicated text
GET /api/crash-files/dsyms/{id}	X-API-Key or a session	One dSYM bundle as a zip

Anonymous crash uploads are limited to 30 a minute per address and answer 202 without storing anything while crash collection is off. A bad credential is refused with 401 rather than treated as anonymous.

APNs device registration

Endpoint	Purpose
POST /api/ios/apns-devices	Register or refresh an APNs device token

The body carries clientRegistrationId, token, tokenEncoding (HEX or BASE64), topic, environment (SANDBOX or PRODUCTION), supportedPushTypes, and displayName. A new registration returns 201, refreshing an existing one returns 200. The body is capped at 32 KiB and each source IP is limited to 120 requests per minute, after which it gets 429. See Push notifications.

Notification device registration

Endpoint	Purpose
POST /api/ios/notification-devices	Register or refresh the device token the control plane’s own iOS app receives notifications on

The body carries clientRegistrationId, token, tokenEncoding, topic, environment, and displayName, plus the optional deviceModel, osVersion, appVersion, appBuild, and locale. Unknown fields are rejected rather than ignored. The response returns the device id, whether it was created, its status, and lastRegisteredAt — 201 for a new registration, 200 for a refresh.

The same 32 KiB body cap and 120-requests-per-minute-per-IP limit apply, counted separately from the push console’s budget. Registered devices are managed on Notifications.

This endpoint is deliberately narrower than /api/ios/apns-devices. It serves one first-party app, so it has no push-type catalog and no certificate authentication.

OpenAPI contract

Endpoint	Returns
GET /api/openapi.json	An OpenAPI 3.1 document covering the codebase, telemetry, APNs, crash, and dSYM endpoints

The document is assembled at request time from the same Zod schemas the handlers validate against, so it cannot drift from the implementation. It describes the cookie and bearer security used by protected operations while leaving integration endpoints explicitly public. The document itself is served with cache-control: public, max-age=300 and is the right thing to point a client generator at.

Browser and agent routes

The dashboard and the control agents use a handful of further routes. They are part of the application’s own plumbing rather than an integration surface, but they are worth knowing when reading logs:

Endpoint	Used by
POST / GET /api/run-attachments, GET /api/run-attachments/{id}	Uploading and fetching files attached to an AI run
GET /api/agent/run-attachments/{id}	An agent fetching an attachment for a run it is executing
GET /api/agent/dsyms/{id}/dwarf	A macOS agent fetching a DWARF file for a crash it is symbolicating
POST /api/build-artifact-uploads/{uploadId}	An agent streaming a finished build artifact to the server
GET /api/worktrees/{worktreeId}/diff-image	Rendering an image diff for a worktree change
POST /api/ios/enrollment/start	Starting a signed iOS device enrollment
GET /api/ios/devices/export.tsv	Exporting device UDIDs for the Apple Developer portal
GET /{locale}/dashboard/builds/{buildId}/output	Opening a build’s authenticated raw terminal output
GET /{locale}/dashboard/commands/runs/{runId}/output	Opening a command run’s authenticated raw terminal output

These stay behind whatever authentication protects the dashboard. /api/ios/enrollment/start and /api/ios/devices/export.tsv in particular must never be added to a Cloudflare Access bypass.

Public endpoints

Everything under /api/public/* is intentionally unauthenticated: iOS enrollment callbacks, short-lived build artifact and over-the-air manifest downloads, rate-limited crash report uploads, and the three signature-verified webhooks. Hosting and networking lists the full path set and explains how to expose exactly that namespace and nothing else.

MCP

/api/mcp is a stateless Streamable HTTP MCP endpoint. Point Claude Code, Cursor, or any other MCP client at it and the server’s built-in tools become callable directly.

The catalog spans agents, builds, codebases, worktrees, commands, workflows, runs, GitHub, GitLab, Jira, skills, notifications, signing, devices, disk space, usage, and debugging. Discovery tools include global_search, get_action_center, get_apps, get_app, get_installation_status, get_agent_cli_health, get_crash_reports, get_crash_report, get_dsyms, and get_dsym. Browse and export the catalog, run tools by hand, and inspect call history from Tools.

Scopes

The same endpoint serves three scopes, selected by query parameter:

URL	Exposes	Authenticated by
/api/mcp	Every built-in tool	Better Auth session or X-API-Key
/api/mcp?preset=<id>	Selected built-in and external tools in that MCP tool preset	Better Auth session or X-API-Key
/api/mcp?run=<runId>	The run’s frozen built-in and external tool selections	An enrolled agent’s credential

Supplying both preset and run, or either one twice, is rejected with 400 INVALID_MCP_SCOPE.

Run scope applies argument-level containment as well as tool-name grants. get_codebase_repository_preparations and save_codebase_repository_preparations may access only the logical repository attached to the run; a preset cannot let a run read or replace another repository’s rules.

Run creation resolves selected tools and stores their membership, advertised names, and schemas. A selected external server must be reachable and must still advertise each selected tool. A later preset edit does not alter an existing run’s snapshot. Legacy runs without mixed snapshots keep their built-in selections.

MCP clients can discover preset IDs with get_mcp_tool_presets and pass mcpPresetIds to create_agent_run, create_run_follow_up, or play_plan. This discovery tool accepts an optional kind of PLAN or SESSION.

Authentication

Unscoped and preset MCP calls require a signed-in user’s session or a Better Auth API key. Scripts should use an aide_ key in X-API-Key. The raw key is shown only once when you create it on API keys.

curl -s http://127.0.0.1:3090/api/mcp \
  -H "X-API-Key: aide_replace-with-created-key" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The run scope is different: it authenticates the caller as an enrolled agent instead, which is what lets a Session on a managed Mac call back into the control plane with exactly the tools its run was granted.

Status	Code	Cause
400	INVALID_MCP_SCOPE	Conflicting or empty preset / run parameters
401	TOOL_API_UNAUTHORIZED	Missing, conflicting, expired, disabled, or invalid credentials
403	RUN_MCP_FORBIDDEN	The run belongs to a different agent
404	RUN_NOT_FOUND / MCP_PRESET_NOT_FOUND	The referenced run or preset does not exist

TOOLS_API_TOKEN is no longer supported. Replace it with an API key sent in X-API-Key; there is no anonymous fallback.

Correlation and auditing

Send an x-request-id header — up to 128 characters — and it is echoed back on the response and recorded as the call’s correlation ID. Without one, the server generates a UUID. Every call is written to the audit log on the Tools page with its caller, source, duration, and a SHA-256 hash of its arguments. Arguments themselves are never stored.

Callers are recorded by their Better Auth user or API-key identity. Run-scoped calls are recorded as agent:<agentId>@<address>.

Tool HTTP API

The Tools page drives two plain HTTP routes, which are also usable directly when you want a single tool call without speaking MCP:

Endpoint	Purpose
GET /api/tools/catalog	The full catalog — groups, tools, and their JSON input and output schemas
POST /api/tools/call	Invoke one tool with { "groupId", "name", "arguments" }

Both Tools routes require a signed-in user session. They do not accept API keys or agent credentials. POST /api/tools/call returns { "result", "requestId" } on success. Failures use INVALID_TOOL_CALL (400), CODEBASE_NOT_FOUND (404), TOOL_CALL_FAILED (502), or a 409 for an ambiguous codebase lookup.

External MCP servers

The Tools page manages and tests external Streamable HTTP or legacy SSE MCP servers. Their tools can be called from the Tools page, workflows, and scoped preset/run MCP connections. Saved custom header values stay server-side and are never returned to the browser.

The bare /api/mcp endpoint remains built-in only. External tools are re-exported only through /api/mcp?preset=<id> and /api/mcp?run=<runId> when selected for that scope.

External MCP aliases have the form aide_ext_<identity-hash>_<tool-label> and are derived from the local server ID and raw upstream name. The same raw name on two servers therefore receives distinct aliases. Renaming a server or changing its catalog prefix does not rename a frozen run’s tools. Use the advertised alias for MCP tools/call; use the raw name with its server reference in preset documents.

External calls resolve credentials at call time. Credential rotation is supported, but a changed endpoint URL or transport is rejected for an existing run. Upstream content, structured results, and MCP error results pass through the scoped connection; failed external calls are recorded in the same tool-call audit as built-ins.

Related pages

GraphQL API

The generated schema reference, subscriptions, and Apollo Studio.

Tools

Browse the tool catalog, build presets, and read the audit log.

Hosting and networking

Which of these paths may be exposed publicly, and which must not be.

Local development

Regenerating the schema and resolver types.

External pipeline actions

externalPipelineActions(repositoryId:) returns the enabled flag, retry/cancel sources, and secret names. Use saveExternalPipelineActions, setExternalPipelineSecret, and deleteExternalPipelineSecret to configure a canonical repository. Existing secret values are never readable.

GitLabPipeline.canRetry/canCancel and GitLabJob.kind/targetUrl/canRetry/canCancel describe server-computed capabilities. Use runGitLabPipelineAction(projectId:, pipelineId:, action:, jobId:) for combined pipeline actions or one external status. Its optional execution reports component outcomes; externalPipelineExecutions returns the latest 20 sanitized records. Legacy pipeline mutations, MCP pipeline tools, and workflow actions use the same dispatch service. Agent credentials cannot manage this control-plane configuration.

mutation RequestExternalRetry($projectId: ID!, $pipelineId: ID!, $jobId: ID) {
  runGitLabPipelineAction(projectId: $projectId, pipelineId: $pipelineId, action: RETRY, jobId: $jobId) {
    pipeline { id status }
    execution { id status nativeStatus externalStatus message targetedStatusIds startedAt completedAt }
  }
}

See the versioned context and failure contract.