API Reference

SemanticFed is API-first. The federated model and all governance are served over a single authenticated GraphQL API.

Endpoints

BURDENOFF_ENV	Workspace gateway	Global gateway
prod (default)	https://graphqlworkspaces.burdenoff.com/workspaces/graphql	https://graphql.burdenoff.com/global/graphql
alpha	https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql	https://alphagraphql.burdenoff.com/global/graphql
local	http://127.0.0.1:4003/workspaces/graphql	http://127.0.0.1:4000/global/graphql

Surfaces

Surface	What it's for	Status
GraphQL API	The federated model and all governance, over one authenticated endpoint	Available
SQL endpoint	A single SQL interface over the whole federated model, for BI tools and apps	Roadmap
CLI	Terminal-native automation and CI/CD against the SemanticFed API	Available
MCP server	Tools, resources, and prompts that expose the governed model to Claude and any MCP-compatible agent	Available
Node.js SDK	Typed, GraphQL-backed programmatic access	Available
Python SDK	The same API surface, idiomatic and async-first, for data and ML workflows	Available

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.

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

• GraphQL API — detailed API usage with examples
• Node SDK
• Python SDK
• CLI Reference