Möbius
Reference

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 as null with a group-level INSUFFICIENT_SCOPE error — 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 to null for a table that is not CERTIFIED.
  • 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 pass includeInputSnapshot: 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 sent data becomes the whole row; any column you omit is reset to NULL (or dropped, on a document-shaped table). Replace-existing-only — a missing row id returns NOT_FOUND, it never creates a new row.
  • upsertRows — a batch of complete rows, resolved by key into an insert (new key value) or a full-replace update (existing key value, same reset-on-omit rule as replaceRow).
  • 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.

On this page