Skip to main content

GraphQL API

The platform exposes a federated GraphQL API.

What you'll learn​

  • The four endpoints and which to use when
  • Conventions: my* vs all*, Connection types, headers
  • How to subscribe to live updates

Environment selection​

All endpoints default to production. Select a different environment by setting BURDENOFF_ENV or by passing explicit URLs:

EnvironmentBURDENOFF_ENVGlobal endpointWorkspace endpoint
Production (default)prodhttps://graphql.burdenoff.com/global/graphqlhttps://graphqlworkspaces.burdenoff.com/workspaces/graphql
Alphaalphahttps://alphagraphql.burdenoff.com/global/graphqlhttps://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql
Locallocalhttp://localhost:4000/global/graphqlhttp://localhost:4003/workspaces/graphql

When BURDENOFF_ENV is unset or invalid, the default is prod.

The four endpoints​

EndpointUse for
https://graphql.burdenoff.com/global/graphqlGlobal/tenant-layer calls (auth, billing, tenant config)
https://graphqlworkspaces.burdenoff.com/workspaces/graphqlWorkspace-layer calls (conversations, files, tags, RBAC)
https://graphql.burdenoff.com/global/graphql (internal port)Service-to-service global
https://graphqlworkspaces.burdenoff.com/workspaces/graphql (internal)Service-to-service workspace

For workspace calls you'll always send x-workspace-id: <uuid>.

Naming conventions​

PatternExampleReturns
my*myWorkspacesThings owned by the caller
all*allUsersEverything in scope (admin)
{thing} (singular)workspace(id:)A single thing by id
{thing}s (plural)workspacesA flat list (small N)

Connection types​

Two flavors of paginated lists:

Relay-style (for unbounded lists):

{
conversations(first: 50, after: "...") {
edges { node { id name } cursor }
pageInfo { hasNextPage endCursor }
}
}

Flat connection (for bounded / small lists):

{
currentUserApps {
apps { id name }
hasMore
totalCount
}
}

Tip: read the field's type. If it ends in Connection with edges/node, it's Relay. If it ends in Connection with a flat apps/items array, it's flat.

Headers​

HeaderRequired?
Authorization: Bearer <token>Always
Content-Type: application/jsonAlways
x-workspace-id: <uuid>Workspace-layer calls

Service-to-service calls also receive x-actor-* and x-consent-* headers from the gateway — see Authentication.

Subscriptions​

GraphQL subscriptions use WebSockets via the graphql-ws protocol. The same endpoint URL, just over wss://.

import { createClient } from 'graphql-ws';
const client = createClient({
url: 'wss://graphqlworkspaces.burdenoff.com/workspaces/graphql',
connectionParams: { authorization: `Bearer ${token}`, 'x-workspace-id': wsId }
});

RBAC​

Every public field carries an @rbac directive. Calling a field you lack permission for returns a typed error. See the RBAC overview.

Next steps​