Skip to main content

GraphQL API

SemanticFed is API-first. The federated model and all governance are served over a single authenticated GraphQL API on the Burdenoff Workspaces platform.

Endpoints​

BURDENOFF_ENVWorkspace gatewayGlobal gateway
prod (default)https://graphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://graphql.burdenoff.com/global/graphql
alphahttps://alphagraphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://alphagraphql.burdenoff.com/global/graphql
localhttp://127.0.0.1:4003/workspaces/graphqlhttp://127.0.0.1:4000/global/graphql

Surfaces​

SurfaceWhat it's forStatus
GraphQL APIThe federated model and all governance, over one authenticated endpointAvailable
SQL endpointA single SQL interface over the whole federated model, for BI tools and appsRoadmap
CLITerminal-native automation and CI/CD against the SemanticFed APIAvailable
MCP serverTools, resources, and prompts that expose the governed model to Claude and any MCP-compatible agentAvailable
Node.js SDKTyped, GraphQL-backed programmatic accessAvailable
Python SDKThe same API surface, idiomatic and async-first, for data and ML workflowsAvailable

What the API covers​

  • Sources — register connectors and data sources, run connection health probes, manage the connectivity lifecycle
  • Model — create and version semantic models; define entities, dimensions, metrics, and relationships
  • Queries — author saved queries, execute them as query runs, and read run history (plan summary, sources touched, duration, row count, cache status)
  • Governance — attach ALLOW/DENY access policies scoped to ROW, COLUMN, or ENTITY
  • Observability — health endpoints (semHealth) and structured run records

Authentication​

All clients authenticate through the same identity layer: OIDC SSO for the web app, OAuth device-code for terminal clients (CLI/MCP), and API keys for automation. Every query and mutation is permission-checked against your role-based access control rules before it executes, and unauthorized operations are rejected.

Calling the API directly​

With graphql-request (Node)​

import { GraphQLClient } from 'graphql-request';

const client = new GraphQLClient(
  'https://graphqlworkspaces.burdenoff.com/workspaces/graphql',
  {
    headers: {
      authorization: `Bearer ${process.env.BURDENOFF_TOKEN}`,
      'x-workspace-id': process.env.WORKSPACE_ID,
    },
  }
);

const data = await client.request(`
  query {
    semConnectors {
      items { id name }
    }
  }
`);

With httpx (Python)​

import httpx

response = httpx.post(
    "https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    json={
        "query": "query { semConnectors { items { id name } } }"
    },
    headers={
        "Authorization": f"Bearer {token}",
        "x-workspace-id": workspace_id,
    },
)
data = response.json()

With curl​

curl -X POST https://graphqlworkspaces.burdenoff.com/workspaces/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BURDENOFF_TOKEN" \
  -H "x-workspace-id: $WORKSPACE_ID" \
  -d '{"query": "query { semHealth { status } }"}'

Naming conventions​

  • All GraphQL fields are prefixed with sem (e.g., semConnectors, semModels, semQueries).
  • All product types are prefixed with Sem (e.g., SemConnector, SemModel, SemQuery).
  • List queries return wrapper connection types shaped { items { ... } pageInfo { ... } }.

Health check​

query {
  semHealth {
    status
    message
  }
}

Next steps​