GraphQL transport and schema

GraphQL is the canonical backend contract.

The CLI is the default public machine interface, but the GraphQL API is the backend contract underneath it. The material below shows transport details, real schema excerpts, and direct query patterns.

Open the CLI tour Open resources

Agent-first route: Start at /agents, inspect /docs/cli, and drop into this page when you need proof, detail, or rollout guidance.

Agent-first route

Humans should usually delegate first-pass evaluation to an agent. Agents should start at /agents, use /docs/cli as the official product tour, and open /docs/graphql only when needed.

Agent-ready surface

Start with the CLI, not browser guesswork.

Preferred route: /agents, then /docs/cli, then /docs/graphql only when lower-level integration details matter.

$ mbr spec export --json
$ mbr auth whoami --json
$ mbr queues list --workspace ws_preview --json

Open GraphQL reference | Open schema.graphql

Canonical backend API

GraphQL is the shared backend contract behind the CLI and the higher-level admin surfaces.

Visible schema

The platform repo publishes a concrete `schema.graphql` file rather than only describing the API abstractly.

Two GraphQL paths

Use `/graphql` for agent and CLI traffic. Use `/admin/graphql` only for browser-session-backed admin workflows.

Same trust model

The API still operates within the same permission, audit, and workspace-scope boundaries as the CLI.

Table of contents

Section map.

Jump directly to the part you need.

The API path depends on auth model and host context. Transport The public platform repo already exposes the GraphQL schema. Schema excerpts Direct API calls follow this shape. Direct query pattern GraphQL is deliberate, not default. When to use GraphQL

Transport

The API path depends on auth model and host context.

GraphQL is not a separate product surface from the CLI. It is the backend contract the CLI and other machine-facing integrations rely on.

Proof bundle

Contract internal/graphql/schema/schema.graphql The canonical GraphQL schema exposed by the platform implementation.
Contract docs/ADRs/0010-agent-api-and-graphql-architecture.md Architecture decision record for the agent API and GraphQL contract.
Implementation cmd/api/routers.go Shows how `/graphql` and `/admin/graphql` are wired at runtime.
Contract docs/swagger.yaml Documents the surrounding REST and auth surfaces that sit beside GraphQL.

`POST /graphql`

Canonical agent and CLI endpoint. Use bearer-token auth and treat it as the default direct machine path.

`POST /admin/graphql`

Session-authenticated admin endpoint used by browser-backed human workflows. Do not treat it as the default agent path.

Adjacent REST endpoints

Use `/health`, `/auth/...`, and `/attachments` for health checks, login bootstrap, and upload flows that are not modeled as GraphQL.

Development playgrounds

The router exposes GraphQL playground routes only outside production environments.

Schema excerpts

The public platform repo already exposes the GraphQL schema.

Use the schema file directly when you need concrete query and mutation roots. The excerpts below are trimmed from the canonical `internal/graphql/schema/schema.graphql` file.

Proof bundle

Contract internal/graphql/schema/schema.graphql The canonical GraphQL schema exposed by the platform implementation.
Contract docs/ADRs/0010-agent-api-and-graphql-architecture.md Architecture decision record for the agent API and GraphQL contract.
Implementation cmd/api/routers.go Shows how `/graphql` and `/admin/graphql` are wired at runtime.
Contract docs/swagger.yaml Documents the surrounding REST and auth surfaces that sit beside GraphQL.

Query root excerpt

These queries show the main read surfaces exposed through GraphQL.

type Query {  me: Principal!  workspace(id: ID!): Workspace  workspaces: [Workspace!]!  teams(workspaceID: ID!): [Team!]!  cases(workspaceID: ID!, filter: CaseFilter): CaseConnection!  queues(workspaceID: ID!): [Queue!]!  conversationSessions(workspaceID: ID!, filter: ConversationSessionFilter): [ConversationSession!]!  knowledgeResources(workspaceID: ID!, filter: KnowledgeResourceFilter): [KnowledgeResource!]!  extensions(workspaceID: ID!): [InstalledExtension!]!  agents(workspaceID: ID!): [Agent!]!}

Mutation root excerpt

These mutations show how work records, knowledge, and extensions are changed through the backend contract.

type Mutation {  createQueue(input: CreateQueueInput!): Queue!  createFormSubmission(input: CreateFormSubmissionInput!): FormSubmission!  addConversationMessage(sessionID: ID!, input: AddConversationMessageInput!): ConversationMessage!  escalateConversation(sessionID: ID!, input: EscalateConversationInput!): Case!  createKnowledgeResource(input: CreateKnowledgeResourceInput!): KnowledgeResource!  updateKnowledgeResource(id: ID!, input: UpdateKnowledgeResourceInput!): KnowledgeResource!  installExtension(input: InstallExtensionInput!): InstalledExtension!  activateExtension(id: ID!): InstalledExtension!}

Direct query pattern

Direct API calls follow this shape.

Use direct GraphQL only when the CLI is too high-level or when an integration already operates over HTTP. The examples below are intentionally minimal and align with the current public repo.

Minimal authenticated query

This is the same minimal `__typename` example shown in the platform repo documentation.

$ curl -sS https://api.your-app-domain/graphql \  -H "Authorization: Bearer hat_YOUR_TOKEN_HERE" \  -H "Content-Type: application/json" \  -d '{"query":"query { __typename }"}'

Prefer the CLI for higher-level inspection

If the goal is to inspect the product shape rather than to embed the backend directly, the CLI remains the better first tool.

$ mbr spec export --json$ mbr queues list --workspace ws_preview --json$ mbr knowledge list --workspace ws_preview --search policy --json

When to use GraphQL

GraphQL is deliberate, not default.

The CLI is easier to reason about for most agent tasks because it groups auth, context, idempotency, and operational verbs into one explicit surface.

Use the CLI first for owned-runtime bootstrap, auth, context, queue and case inspection, knowledge flows, and extension lifecycle work.
Use GraphQL when you need lower-level structured reads or writes that fit an existing integration surface better than shelling out to `mbr`.
Do not treat `/admin/graphql` as interchangeable with `/graphql`; they carry different auth expectations and host contexts.
Read the schema file directly before assuming query or mutation fields exist.

References

Canonical next surfaces.

Each link goes to the next authoritative page, reference, or support surface.

Let agents inspect the CLI-first surface. Let humans decide trust, rollout, and boundaries.

Start from /agents, use /docs/cli as the official product tour, inspect /resources for source and proof, and review /security before making deployment or data-handling decisions.

Open /agents Open resources