Skip to article
Source of Truthfor Life Sciences / Developer guide
Explore the application ↗
Architecture / Developer documentation

GraphQL reference

This reference is generated from the schemas and registered operations used by the server. The public endpoints accept their registered operation hashes; the local-only explorer retains its existing development boundary.

Plate and Corridor reads

Endpoint: /graphql. Source: server/graphql/schema.graphql.

Schema

"""
Public synthetic scenarios. Canonical policy scopes Plate records and fields;
Corridor describes the shared workflow.
"""
type Query {
  dataSource: DataSource!
  corridor: Corridor!
  plate(id: ID!): Plate
  well(plateId: ID!, id: ID!): Well
  result(id: ID!): Result
}

enum DataMode {
  STORED
  EXAMPLE
}

type DataSource {
  mode: DataMode!
}

type PageInfo {
  endCursor: String
  hasNextPage: Boolean!
}

type Corridor {
  id: ID!
  asOf: String!
  lanes(first: Int = 20, after: String): LaneConnection!
  cards(laneId: ID, first: Int = 20, after: String): CardConnection!
  connections(first: Int = 20, after: String): WorkflowConnection!
}

enum LaneStage {
  wet_lab
  dry_lab
  interpretation
}

enum CardKind {
  process
  state_major
  state_minor
  control
  nested
}

enum ConnectionKind {
  flow
  reciprocal
  review
  deferred
}

type Lane {
  id: ID!
  label: String!
  shortLabel: String!
  description: String!
  stage: LaneStage!
  order: Int!
  color: String!
  accentColor: String!
}

type Card {
  id: ID!
  label: String!
  kind: CardKind!
  position: Float!
  note: String
  lane: Lane!
}

type WorkflowLink {
  id: ID!
  kind: ConnectionKind!
  from: Card!
  to: Card!
}

type LaneEdge {
  cursor: String!
  node: Lane!
}

type LaneConnection {
  edges: [LaneEdge!]!
  totalCount: Int!
  pageInfo: PageInfo!
}

type CardEdge {
  cursor: String!
  node: Card!
}

type CardConnection {
  edges: [CardEdge!]!
  totalCount: Int!
  pageInfo: PageInfo!
}

type WorkflowEdge {
  cursor: String!
  node: WorkflowLink!
}

type WorkflowConnection {
  edges: [WorkflowEdge!]!
  totalCount: Int!
  pageInfo: PageInfo!
}

type Plate {
  id: ID!
  asOf: String!
  rows: Int!
  columns: Int!
  wells(first: Int = 20, after: String): WellConnection!
}

enum WellRole {
  sample
  positive_control
  negative_control
  empty
}

enum Consent {
  active
  pending
  rescinded
  expired
}

type Well {
  """
  Coordinate within its plate, for example C3. Use plateId with id for lookup.
  """
  id: ID!
  plateId: ID!
  asOf: String!
  row: Int!
  column: Int!
  role: WellRole!
  sampleId: ID
  assay: String
  consent: Consent
  contaminationProbability: Float
  corridorCard: Card
  history(first: Int = 20, after: String): ResultConnection!
}

enum ResultKind {
  primary
  top_up
  reprep
  reanalysis
  longitudinal
  matched_normal
  orthogonal
  reflex
  control
}

enum ResultStatus {
  reportable
  superseded
  failed_qc
  in_progress
  held
  cancelled
  informational
}

type Result {
  id: ID!
  wellId: ID!
  sequence: Int!
  kind: ResultKind!
  status: ResultStatus!
  title: String!
  label: String!
  assayLabel: String!
  specimenType: String!
  pipeline: String!
  runDate: String!
  reason: String!
  finding: String
  consent: Consent!
  physicalPlateId: ID!
  physicalWellId: ID!
  supersedes: Result
  flowCell: String
  trigger: ResultTrigger
  metrics: [ResultMetric!]!
  ctDna: CtDnaReadout
  minWriteRole: WriteRole!
  specimenId: ID
  patientCode: String
  seriesLabel: String
  artifactsRestricted: Boolean
  artifacts(first: Int = 20, after: String): ArtifactConnection!
}

enum WriteRole {
  viewer
  analyst
  reviewer
  lab_operator
  arc_lead
  auditor
  admin
}

enum MetricComparator {
  gte
  lte
}

type ResultMetric {
  key: String!
  label: String!
  value: Float!
  unit: String!
  target: Float
  comparator: MetricComparator
}

type ResultTrigger {
  source: String!
  refId: String
  detail: String!
}

type CtDnaReadout {
  detected: Boolean!
  meanVafPct: Float!
  tracked: Int!
  detectedCount: Int!
  mtmPerMl: Float
  emerging: String
}

enum RestoreState {
  in_progress
  restored
}

enum RestoreTier {
  expedited
  standard
  bulk
}

type ArtifactRestore {
  state: RestoreState!
  tier: RestoreTier!
  requestedAt: String!
  readyAt: String
  expiresAt: String
}

enum FileKind {
  qc
  vcf
  calls
  gvcf
  bam
  cram
  fastq
  idat
}

type File {
  """Stable object key: reused files keep the same identity across results."""
  id: ID!
  kind: FileKind!

  """
  Integer byte count represented as Float because GraphQL Int is signed 32-bit.
  """
  sizeBytes: Float!
  createdAt: String!
  lifecycleRuleId: ID!
}

type ArtifactReference {
  id: ID!
  file: File!
  reusedFrom: Result
  legalHold: Boolean!
  restore: ArtifactRestore
}

type WellEdge {
  cursor: String!
  node: Well!
}

type WellConnection {
  edges: [WellEdge!]!
  totalCount: Int!
  pageInfo: PageInfo!
}

type ResultEdge {
  cursor: String!
  node: Result!
}

type ResultConnection {
  edges: [ResultEdge!]!
  totalCount: Int!
  pageInfo: PageInfo!
}

type ArtifactEdge {
  cursor: String!
  node: ArtifactReference!
}

type ArtifactConnection {
  edges: [ArtifactEdge!]!
  totalCount: Int!
  pageInfo: PageInfo!
}

Approved operations

CorridorCards

SHA-256: 9bb1bbd6e3f78dbf066a58336ecec83c6febe4a8212132fc997c72cf356b3f4b

query CorridorCards($laneId: ID, $first: Int = 20, $after: String) {
  corridor {
    cards(laneId: $laneId, first: $first, after: $after) {
      totalCount
      pageInfo { endCursor hasNextPage }
      edges { cursor node { id label kind position note lane { id label } } }
    }
  }
}

CorridorConnections

SHA-256: 65d1e68b433f5f0ea2e24c44b18eb4b8745dbae10a0685e5241bef8f461f517b

query CorridorConnections($first: Int = 20, $after: String) {
  corridor {
    connections(first: $first, after: $after) {
      totalCount
      pageInfo { endCursor hasNextPage }
      edges { cursor node { id kind from { id label } to { id label } } }
    }
  }
}

CorridorOverview

SHA-256: 91283eb7184380b092a2d6855b7d906d146907bb2a687395c6d9865c8efce12a

query CorridorOverview($first: Int = 20, $after: String) {
  corridor {
    id
    asOf
    lanes(first: $first, after: $after) {
      totalCount
      pageInfo { endCursor hasNextPage }
      edges { cursor node { id label shortLabel description stage order color accentColor } }
    }
  }
}

PlateHistory

SHA-256: a66a718f0ba28b3532287d3b6e481fb0502f88e98b0c2ea63bc677309f480cf2

query PlateHistory($plateId: ID!, $id: ID!) {
  dataSource {
    mode
  }
  well(plateId: $plateId, id: $id) {
    id
    plateId
    asOf
    row
    column
    role
    sampleId
    assay
    consent
    contaminationProbability
    history(first: 50) {
      totalCount
      pageInfo {
        hasNextPage
      }
      edges {
        node {
          id
          wellId
          sequence
          kind
          status
          label
          title
          specimenType
          assayLabel
          physicalPlateId
          physicalWellId
          flowCell
          pipeline
          runDate
          reason
          finding
          consent
          minWriteRole
          artifactsRestricted
          specimenId
          patientCode
          seriesLabel
          trigger {
            source
            refId
            detail
          }
          supersedes {
            id
          }
          metrics {
            key
            label
            value
            unit
            target
            comparator
          }
          ctDna {
            detected
            meanVafPct
            tracked
            detectedCount
            mtmPerMl
            emerging
          }
          artifacts(first: 8) {
            totalCount
            pageInfo {
              hasNextPage
            }
            edges {
              node {
                legalHold
                reusedFrom {
                  id
                }
                file {
                  id
                  kind
                  sizeBytes
                  createdAt
                  lifecycleRuleId
                }
                restore {
                  state
                  tier
                  requestedAt
                  readyAt
                  expiresAt
                }
              }
            }
          }
        }
      }
    }
  }
}

PlateOverview

SHA-256: f84d7502ab4239349b2d4c49ccf9b3713552919cc51f54fbcd249e052af67fef

query PlateOverview($id: ID!, $first: Int = 24, $after: String) {
  plate(id: $id) {
    id asOf rows columns
    wells(first: $first, after: $after) {
      totalCount
      pageInfo { endCursor hasNextPage }
      edges {
        cursor
        node { id plateId row column role sampleId assay consent contaminationProbability corridorCard { id label } }
      }
    }
  }
}

ResultDetails

SHA-256: e24228967b9e4dda850dc47ec855ce192a97d365dd251bf23ea4e62c6adf6243

query ResultDetails($id: ID!, $first: Int = 20, $after: String) {
  result(id: $id) {
    id wellId title assayLabel specimenType pipeline runDate reason finding consent
    artifacts(first: $first, after: $after) {
      totalCount
      pageInfo { endCursor hasNextPage }
      edges { cursor node { id legalHold reusedFrom { id } file { id kind sizeBytes createdAt lifecycleRuleId } } }
    }
  }
}

WellHistory

SHA-256: 0eacd6ad7207bb05061e7facfc0af484751ca0e2ff9b491e451abf16f07cc6b4

query WellHistory($plateId: ID!, $id: ID!, $first: Int = 12, $after: String) {
  well(plateId: $plateId, id: $id) {
    id plateId
    history(first: $first, after: $after) {
      totalCount
      pageInfo { endCursor hasNextPage }
      edges {
        cursor
        node {
          id sequence kind status label title runDate pipeline reason finding
          physicalPlateId physicalWellId
          supersedes { id }
        }
      }
    }
  }
}

Disposable Source workspaces

Endpoint: /workspace/graphql. Source: server/workspaces/schema.graphql.

Schema

"""An isolated, expiring workspace for public example edits."""
type Query {
  workspaceStatus: WorkspaceStatus!
  workspaceSnapshot: WorkspaceSnapshot!
  workspaceSource(id: ID!): WorkspaceSourceResult!
  workspaceHistory(sourceId: ID!, limit: Int = 20): WorkspaceHistoryResult!
}

type Mutation {
  startWorkspace: WorkspaceStatus!
  resetWorkspace: WorkspaceStatus!
  saveSource(input: SaveSourceInput!): WorkspaceCommandResult!
  restoreSource(input: RestoreSourceInput!): WorkspaceCommandResult!
}

enum WorkspaceCode {
  OK
  LOCAL
  ABSENT
  EXPIRED
  DENIED
  INVALID
  CONFLICT
  QUOTA
  UNAVAILABLE
  MISSING
}

type VisitorWorkspace {
  id: ID!
  createdAt: String!
  expiresAt: String!
  eventCount: Int!
}

type WorkspaceSource {
  id: ID!
  revision: Int!
  title: String!
  description: String!
  tags: [String!]!
}

"""
The selected example persona, separate from the server-issued workspace.
"""
type ScenarioActor {
  principalId: String!
  roleId: String!
  environment: String!
}

enum WorkspaceAction {
  save
  restore
}

type WorkspaceEvent {
  id: ID!
  sourceId: ID!
  action: WorkspaceAction!
  actor: ScenarioActor!
  createdAt: String!
  expectedRevision: Int!
  resultRevision: Int!
}

type WorkspaceStatus {
  code: WorkspaceCode!
  message: String!
  available: Boolean!
  workspace: VisitorWorkspace
}

type WorkspaceSnapshot {
  code: WorkspaceCode!
  message: String!
  workspace: VisitorWorkspace
  sources: [WorkspaceSource!]!
}

type WorkspaceSourceResult {
  code: WorkspaceCode!
  message: String!
  workspace: VisitorWorkspace
  source: WorkspaceSource
}

type WorkspaceHistoryResult {
  code: WorkspaceCode!
  message: String!
  workspace: VisitorWorkspace
  events: [WorkspaceEvent!]!
}

type WorkspaceCommandResult {
  code: WorkspaceCode!
  message: String!
  workspace: VisitorWorkspace
  source: WorkspaceSource
  changed: Boolean!
  replayed: Boolean!
}

input SourceMetadataInput {
  title: String!
  description: String!
  tags: [String!]!
}

input SaveSourceInput {
  id: ID!
  expectedRevision: Int!
  idempotencyKey: ID!
  metadata: SourceMetadataInput!
}

input RestoreSourceInput {
  id: ID!
  expectedRevision: Int!
  idempotencyKey: ID!
}

Approved operations

WorkspaceStatus

SHA-256: 7a1850715aa07dc86311bf476a7fbe06047781971e518d71d82eac011b211923

query WorkspaceStatus {
  workspaceStatus {
    code
    message
    available
    workspace {
      id
      createdAt
      expiresAt
      eventCount
    }
  }
}

WorkspaceSnapshot

SHA-256: 93e0e9d023b642a6f68e2c986ef87cb5650dd1002b138ed349a7c2e8931936c6

query WorkspaceSnapshot {
  workspaceSnapshot {
    code
    message
    workspace {
      id
      createdAt
      expiresAt
      eventCount
    }
    sources {
      id
      revision
      title
      description
      tags
    }
  }
}

WorkspaceSource

SHA-256: b27c468d58e81eac92cb14c1bdb6d2283c1158db932a6d3cac4779d9affce616

query WorkspaceSource($id: ID!) {
  workspaceSource(id: $id) {
    code
    message
    workspace {
      id
      createdAt
      expiresAt
      eventCount
    }
    source {
      id
      revision
      title
      description
      tags
    }
  }
}

WorkspaceHistory

SHA-256: 6972326894590e55fe2d41d38592d5c0eadd546dec210e0139266f07155d994e

query WorkspaceHistory($sourceId: ID!, $limit: Int = 20) {
  workspaceHistory(sourceId: $sourceId, limit: $limit) {
    code
    message
    workspace {
      id
      createdAt
      expiresAt
      eventCount
    }
    events {
      id
      sourceId
      action
      actor {
        principalId
        roleId
        environment
      }
      createdAt
      expectedRevision
      resultRevision
    }
  }
}

StartWorkspace

SHA-256: d2d0cfc354979318c173c8a6be4746ff1689c98d99f0374d9f6e59b9b53b128a

mutation StartWorkspace {
  startWorkspace {
    code
    message
    available
    workspace {
      id
      createdAt
      expiresAt
      eventCount
    }
  }
}

ResetWorkspace

SHA-256: adf6dfa8bef0b90ae15dc7abbcbf76be1e1ff4dfa286bc5d3a403d34410eebcd

mutation ResetWorkspace {
  resetWorkspace {
    code
    message
    available
    workspace {
      id
      createdAt
      expiresAt
      eventCount
    }
  }
}

SaveSource

SHA-256: b0882602289162289c8618be4e0070dcdcb36700ef6a1cb7229c68191b24d130

mutation SaveSource($input: SaveSourceInput!) {
  saveSource(input: $input) {
    code
    message
    changed
    replayed
    workspace {
      id
      createdAt
      expiresAt
      eventCount
    }
    source {
      id
      revision
      title
      description
      tags
    }
  }
}

RestoreSource

SHA-256: de7aa872ae7d9f097111e2b7e18bee96d4d88db7b7514a28dc8c1aa80bcde2c3

mutation RestoreSource($input: RestoreSourceInput!) {
  restoreSource(input: $input) {
    code
    message
    changed
    replayed
    workspace {
      id
      createdAt
      expiresAt
      eventCount
    }
    source {
      id
      revision
      title
      description
      tags
    }
  }
}

Send an approved operation

Use the hash above with the variables declared by that operation. The request's current scenario and workspace cookie still determine its permission and storage scope. This documentation sends no requests or commands.

{
  "extensions": {
    "persistedQuery": {
      "version": 1,
      "sha256Hash": "<registered hash>"
    }
  },
  "variables": {}
}