GraphQL API reference
Query certified tables, data groups, and the predictions ledger through the Möbius GraphQL gateway.
The GraphQL gateway is a standalone door onto certified data — the same governance guarantees as the REST and MCP gateways, in a single schema. It is machine-only: every request carries a service token, never a personal login session (see REST API reference for the token model — the same tokens work across REST, GraphQL, and MCP).
Endpoint and auth
POST {{graphqlBaseUrl}}/graphql
Authorization: Bearer <your-integration-token>Every request is authenticated before the query runs. A missing or invalid token is refused
before any resolver executes. The same per-table scopes that gate REST and MCP (tables:<name>:read,
tables:<name>:write) gate every field here — there is no broader "read all tables" scope.
Table addressing
id / tableId arguments across this schema are the table name (its slug), not an internal
database id — the same addressing REST and MCP use. Row arguments (rowId) are the row's own id.
Query surface
type Query {
table(id: ID!): CertifiedTable
tables(filter: TableFilter, limit: Int, cursor: String): TableConnection!
dataGroup(id: ID!): DataGroup
dataGroups(limit: Int, cursor: String): DataGroupConnection!
certificationReport(tableId: ID!): Governance
predictions(
tableId: ID!
connectorId: ID
status: String
minConfidence: Float
from: DateTime
to: DateTime
limit: Int
cursor: String
includeInputSnapshot: Boolean
): PredictionConnection!
}table/tables— table metadata, certification status, and the Governance Envelope (below). This door serves no row values — it answers "is this table safe, and what does it look like," not "give me the rows." For row values, use the REST or MCP gateway.dataGroup/dataGroups— a data group's decision views. A data group is approved, not certified; its member tables are what is certified. Access is all-or-nothing: a token may read a group only if it can read every member table. A group the token cannot fully read comes back asnullwith a group-levelINSUFFICIENT_SCOPEerror — it is never returned with some member tables silently stripped.certificationReport— despite the name, this returns the verdict, not the full certification evidence report. The evidence itself (predicate results, decision boundaries) is governance evidence and never crosses this door; it stays internal to your Möbius workspace. Resolves tonullfor a table that is notCERTIFIED.predictions— the governed ML predictions ledger for a source table: a model's verdict about a record, not the record itself.inputSnapshot(the one field that can carry your own row values) is withheld unless you passincludeInputSnapshot: true, and is PII-masked against the source table's declared column classifications when served.
Partial list results
List queries never silently omit rows you can't see. tables and dataGroups return the items
your token can read plus _meta { returned, hidden, total, cursor, hasMore }, so a narrower scope
is always visible in the response rather than looking like an empty result. predictions carries
a different _meta shape — { returned, nextCursor, piiFieldsMasked, sourceTableEnvironmentLabel }
— because a predictions page has no fixed total to report against.
Mutation surface
type Mutation {
insertRows(tableId: ID!, rows: [JSON!]!): InsertRowsResult!
updateRow(tableId: ID!, rowId: ID!, data: JSON!): MutationGateResult!
replaceRow(tableId: ID!, rowId: ID!, data: JSON!): MutationGateResult!
upsertRows(tableId: ID!, rows: [JSON!]!, key: String!): UpsertRowsResult!
deleteRow(tableId: ID!, rowId: ID!): MutationGateResult!
}Every mutation requires tables:<name>:write and is evaluated by the same row gate the REST and
MCP write paths use before anything is committed.
insertRows— add one or more rows. Rejected rows are recorded, not silently dropped.updateRow— partial update (PATCH semantics): only the fields you send are changed.replaceRow— full replace (PUT semantics): the sentdatabecomes the whole row; any column you omit is reset toNULL(or dropped, on a document-shaped table). Replace-existing-only — a missing row id returnsNOT_FOUND, it never creates a new row.upsertRows— a batch of complete rows, resolved bykeyinto an insert (new key value) or a full-replace update (existing key value, same reset-on-omit rule asreplaceRow).deleteRow— a soft delete. The row is never hard-deleted.
Bulk writes above your workspace's synchronous ceiling. insertRows and upsertRows return a
GraphQL union: either the full per-row result (MutationGateResult / UpsertRowsGateResult)
inline, or — for a batch larger than your workspace's synchronous ceiling — an AsyncJobAccepted
with a jobId you poll via GET /api/mb/jobs/{jobId} for the final outcome. Because this is a
union, select through inline fragments on both possible shapes:
mutation {
insertRows(tableId: "orders", rows: [...]) {
... on MutationGateResult {
accepted { id rowIndex }
rejected { rowIndex predicate severity reason }
}
... on AsyncJobAccepted {
jobId
expectedRowCount
}
}
}In-place tables (data that lives in your own warehouse, not in Möbius) accept write scopes but refuse the write itself — Möbius does not write into your warehouse on your behalf.
The Governance Envelope
Every CertifiedTable carries a governance field — the same composed "is this data safe to act
on" verdict every Möbius door stamps (REST's meta.governance, the MCP governance block, and
this field):
type Governance {
envelopeVersion: String!
verdict: String! # SAFE | NOT_SAFE | ADVISORY
certificationStatus: String!
gateMode: String # ENFORCING | ADVISORY | OFF
certifiedAt: DateTime
schemaVersion: String
subject: GovernanceSubject!
freshness: GovernanceFreshness!
pii: GovernancePii!
reasons: [String!]!
modeAOutputGate: ModeAOutputGate
evaluatedAt: String!
}Because this door serves table metadata rather than rows, pii is always
{ masked: false, fields: [] } here — PII disclosure is a concern of the row-serving doors (REST,
MCP), not this one. reasons is populated when the verdict is NOT_SAFE or ADVISORY, and empty
when SAFE. For an in-place table (Mode A), modeAOutputGate discloses the watermark its
certified view is pinned at, whether Möbius knows of un-vouched rows past that fence, and which
warehouse object a row read resolves against; it's null for held tables (Mode B), and also for
an in-place table with no resolvable output-gate state.
Errors
GraphQL errors follow the standard errors[] array with a typed extensions.code:
{
"data": { "dataGroup": null },
"errors": [
{
"message": "Insufficient scope for data group: revenue",
"path": ["dataGroup"],
"extensions": { "code": "INSUFFICIENT_SCOPE", "resourceId": "dg_123", "resourceType": "DATAGROUP" }
}
]
}Common codes: UNAUTHORIZED (missing or invalid token), FORBIDDEN (the GraphQL door is disabled
for your workspace, or the token's workspace is unresolvable), LICENSE_HARD_STOP (a
Connect/Enclave instance's license has lapsed past its grace period), INSUFFICIENT_SCOPE (your
token can't read/write the requested resource), NOT_FOUND (a replaceRow/updateRow/deleteRow
target that doesn't exist), UPSERT_KEY_NOT_FOUND (the key column named in upsertRows doesn't
exist on the table), ENV_MISMATCH (the resource's environment isn't one your token is scoped to
— the multi-environment refusal), INVALID_CURSOR (a pagination cursor you passed is malformed),
UNKNOWN_COLUMN_KEYS (a write named a column that doesn't exist on the table), and
BAD_USER_INPUT (a malformed argument, such as an empty key on upsertRows).
Field-level partial access shows up inside errors[] with a per-field INSUFFICIENT_SCOPE for
table field selections your token can't read — data groups and decision views, by contrast, are
all-or-nothing (see above).
Certification gate
Every read is gated on the table's lifecycle state being CERTIFIED. There is no configuration
that bypasses this — an uncertified table simply isn't reachable through this door, or through
REST or MCP.