GraphQL API
The platform exposes a federated GraphQL API.
What you'll learn
- The four endpoints and which to use when
- Conventions:
my*vsall*, 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:
| Environment | BURDENOFF_ENV | Global endpoint | Workspace endpoint |
|---|---|---|---|
| Production (default) | prod | https://graphql.burdenoff.com/global/graphql | https://graphqlworkspaces.burdenoff.com/workspaces/graphql |
| Alpha | alpha | https://alphagraphql.burdenoff.com/global/graphql | https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql |
| Local | local | http://localhost:4000/global/graphql | http://localhost:4003/workspaces/graphql |
When BURDENOFF_ENV is unset or invalid, the default is prod.
The four endpoints
| Endpoint | Use for |
|---|---|
https://graphql.burdenoff.com/global/graphql | Global/tenant-layer calls (auth, billing, tenant config) |
https://graphqlworkspaces.burdenoff.com/workspaces/graphql | Workspace-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
| Pattern | Example | Returns |
|---|---|---|
my* | myWorkspaces | Things owned by the caller |
all* | allUsers | Everything in scope (admin) |
{thing} (singular) | workspace(id:) | A single thing by id |
{thing}s (plural) | workspaces | A 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
| Header | Required? |
|---|---|
Authorization: Bearer <token> | Always |
Content-Type: application/json | Always |
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
- GraphQL Reference — live schema
- Node SDK — generated typed client
- Python SDK
- Webhooks — push events instead of polling