Queries

Every read operation in Golden Reports goes through a single GraphQL endpoint. This page documents every field on the root Query type, grouped by the resource it returns.

Overview

POST https://api.goldenreports.dev/graphql

All queries require a bearer token (see Authentication). Object identifiers are UUID scalars and timestamps are returned as ISO 8601 strings on the DateTime scalar.

Pagination, filtering, and sorting

List queries (workspaces, reports, dataContexts, dataSources, creditTransactions) share the same shape. Each one accepts a paging: PagingInput argument and returns a *NodesPage envelope:

  • Name
    paging.cursor
    Type
    ID
    Description

    Opaque cursor returned by the previous page. Omit on the first call.

  • Name
    paging.limit
    Type
    Int
    Description

    Page size. Defaults to the server-side limit; cap depends on the resource.

  • Name
    items
    Type
    [T!]!
    Description

    The current page of nodes.

  • Name
    cursor
    Type
    ID
    Description

    Cursor to pass back as paging.cursor for the next page. null once exhausted.

Sorting uses the same envelope across resources: a sort: { fields: [{ field, direction }] } input where field is one of NAME or CREATED_AT and direction is ASC or DESC.

Paginating workspaces

query Workspaces($cursor: ID) {
  workspaces(
    paging: { cursor: $cursor, limit: 25 }
    sort: { fields: [{ field: NAME, direction: ASC }] }
  ) {
    items { id name }
    cursor
  }
}

Workspaces

Workspaces are the top-level container for projects, data contexts, data sources, and reports.

List workspaces

Returns a paged list of every workspace the caller can see.

Arguments

  • Name
    paging
    Type
    PagingInput
    Description

    Cursor pagination — see Pagination.

  • Name
    sort
    Type
    WorkspaceSortingInput
    Description

    Sort by NAME or CREATED_AT (ASC or DESC).

Returns WorkspaceNodesPage!.

Request

QUERY
workspaces
query {
  workspaces {
    items {
      id
      name
      description
      projects {
        id
        name
      }
    }
    cursor
  }
}

Response

{
  "data": {
    "workspaces": {
      "items": [
        {
          "id": "8b3f…",
          "name": "Acme Reporting",
          "description": null,
          "projects": [{ "id": "1ad2…", "name": "Default" }]
        }
      ],
      "cursor": null
    }
  }
}

Get a workspace

Returns a single workspace by id, or null if it doesn't exist or the caller can't see it.

Arguments

  • Name
    id
    Type
    UUID!
    Description

    The workspace identifier.

Workspace fields

  • Name
    id
    Type
    UUID!
    Description
    Workspace identifier.
  • Name
    name
    Type
    String!
    Description
    Display name.
  • Name
    description
    Type
    String
    Description
    Optional description.
  • Name
    projects
    Type
    [Project!]!
    Description
    All projects in this workspace.

Request

QUERY
workspace
query Workspace($id: UUID!) {
  workspace(id: $id) {
    id
    name
    description
    projects {
      id
      name
      description
    }
  }
}

Reports

Reports are render-spec + GraphQL-query bundles that produce HTML or Excel output.

List reports

Arguments

  • Name
    filter.codes
    Type
    [String!]
    Description

    Filter by one or more report codes.

  • Name
    filter.projectId
    Type
    UUID
    Description

    Restrict to a single project.

  • Name
    paging
    Type
    PagingInput
    Description
    Cursor pagination.
  • Name
    sort
    Type
    ReportSortingInput
    Description
    Sort by NAME or CREATED_AT.

Returns ReportNodesPage!.

Request

QUERY
reports
query Reports($projectId: UUID) {
  reports(filter: { projectId: $projectId }) {
    items {
      id
      code
      name
      renderSpecType
      version
      createdAt
    }
    cursor
  }
}

Get a report

Arguments

  • Name
    id
    Type
    UUID!
    Description
    The report identifier.

Report fields

  • Name
    id
    Type
    UUID!
    Description
    Report identifier.
  • Name
    code
    Type
    String!
    Description
    Stable, human-friendly code used by embeddedReport and exportedReport.
  • Name
    name
    Type
    String!
    Description
    Display name.
  • Name
    description
    Type
    String
    Description
    Optional description.
  • Name
    renderSpecType
    Type
    RenderSpecType!
    Description
    HTML or EXCEL.
  • Name
    renderSpecData
    Type
    JSON
    Description
    Renderer-specific layout configuration.
  • Name
    graphQlQuery
    Type
    String
    Description
    The GraphQL query the report executes against its data context.
  • Name
    variables
    Type
    JSON
    Description
    Internal variables resolved at render time.
  • Name
    parameters
    Type
    JSON
    Description
    User-facing parameter definitions (what callers can override).
  • Name
    version
    Type
    Int!
    Description
    Monotonically increasing version, bumped on every save.
  • Name
    createdAt
    Type
    DateTime!
    Description
    Creation timestamp.
  • Name
    lastModifiedAt
    Type
    DateTime
    Description
    Last modification timestamp.
  • Name
    project
    Type
    Project!
    Description
    The owning project.
  • Name
    dataContext
    Type
    DataContext!
    Description
    The data context the report queries against.
  • Name
    createdBy
    Type
    User!
    Description
    User who created the report.
  • Name
    lastModifiedBy
    Type
    User
    Description
    User who last modified the report.

Request

QUERY
report
query Report($id: UUID!) {
  report(id: $id) {
    id
    code
    name
    renderSpecType
    parameters
    dataContext { id name }
    project { id name }
  }
}

Rendering & export

Embedded report

Renders a report to HTML for in-page embedding. Returns an HTML payload plus a short-lived session token suitable for streaming follow-up requests (e.g. interactive parameters).

Arguments

  • Name
    code
    Type
    String!
    Description
    The report's code.
  • Name
    parameters
    Type
    JSON
    Description
    Runtime parameter overrides keyed by parameter name.

Returns GetEmbeddedReportResult

  • Name
    html
    Type
    String
    Description
    Rendered HTML content.
  • Name
    sessionId
    Type
    ID
    Description
    Render session identifier.
  • Name
    sessionToken
    Type
    String
    Description
    Short-lived session authentication token.

Request

QUERY
embeddedReport
query Embed($code: String!, $params: JSON) {
  embeddedReport(code: $code, parameters: $params) {
    html
    sessionId
    sessionToken
  }
}

Exported report

Exports a report to PDF or Excel. Returns a presigned download URL. Provide either pdf or excel options — the option you provide selects the output format.

Arguments

  • Name
    code
    Type
    String!
    Description
    The report's code.
  • Name
    parameters
    Type
    JSON
    Description
    Runtime parameter overrides.
  • Name
    pdf
    Type
    PdfExportOptionsInput
    Description

    paperSize (A4, LETTER, LEGAL, A3), orientation (PORTRAIT, LANDSCAPE), and optional margins.

  • Name
    excel
    Type
    ExcelExportOptionsInput
    Description

    Optional sheetName for the produced workbook.

Returns GetExportedReportResult

  • Name
    downloadUrl
    Type
    String
    Description
    Presigned URL for the exported file.

Request

QUERY
exportedReport
query ExportPdf($code: String!) {
  exportedReport(
    code: $code
    pdf: { paperSize: A4, orientation: PORTRAIT }
  ) {
    downloadUrl
  }
}

Templates & themes

List templates

Returns every report template available to the tenant. Templates seed new reports through createReport.

Template fields

  • Name
    id
    Type
    UUID!
    Description
    Template identifier.
  • Name
    name
    Type
    String!
    Description
    Display name.
  • Name
    description
    Type
    String!
    Description
    Long-form description.
  • Name
    renderSpecType
    Type
    RenderSpecType!
    Description
    HTML or EXCEL.
  • Name
    category
    Type
    TemplateCategory!
    Description
    USE_CASE or SAMPLE.
  • Name
    enabled
    Type
    Boolean!
    Description
    Whether the template is currently selectable.
  • Name
    thumbnailUrl
    Type
    String
    Description
    Optional thumbnail URL.
  • Name
    icon
    Type
    String
    Description
    Optional inline SVG icon.

Request

QUERY
templates
query {
  templates {
    id
    name
    category
    renderSpecType
    enabled
  }
}

List themes

Returns every report theme available to the tenant. Themes are CSS payloads applied to HTML renders.

ReportTheme fields

  • Name
    id
    Type
    UUID!
    Description
    Theme identifier.
  • Name
    code
    Type
    String!
    Description
    Machine-readable code.
  • Name
    name
    Type
    String!
    Description
    Display name.
  • Name
    value
    Type
    String!
    Description
    The CSS content of the theme.
  • Name
    description
    Type
    String
    Description
    Optional description.
  • Name
    active
    Type
    Boolean!
    Description
    Whether the theme is enabled.

Request

QUERY
themes
query {
  themes { id code name active }
}

Data contexts

A data context is a versioned schema + GraphQL query layer that sits on top of one or more data sources. Reports execute their graphQlQuery against a data context. Drafts are mutable; publishing creates an immutable DataContextVersion.

List data contexts

Arguments

  • Name
    filter.codes
    Type
    [String!]
    Description
    Filter by one or more data context codes.
  • Name
    filter.projectId
    Type
    UUID
    Description
    Restrict to a single project.
  • Name
    paging
    Type
    PagingInput
    Description
    Cursor pagination.
  • Name
    sort
    Type
    DataContextSortingInput
    Description
    Sort by NAME or CREATED_AT.

Returns DataContextNodesPage!.

Request

QUERY
dataContexts
query {
  dataContexts(paging: { limit: 25 }) {
    items {
      id
      code
      name
      revision
      lastPublishedVersionId
    }
    cursor
  }
}

Get a data context

Returns the current draft state of a data context.

DataContext fields

  • Name
    id
    Type
    UUID!
    Description
    Data context identifier.
  • Name
    code
    Type
    String!
    Description
    Stable code.
  • Name
    name
    Type
    String!
    Description
    Display name.
  • Name
    description
    Type
    String
    Description
    Optional description.
  • Name
    schema
    Type
    String!
    Description
    SDL of the GraphQL schema the data context exposes to reports.
  • Name
    designerState
    Type
    JSON
    Description
    Opaque designer-tool state.
  • Name
    revision
    Type
    Int!
    Description
    Current draft revision — increments on every auto-save.
  • Name
    draftId
    Type
    UUID!
    Description
    Identifier of the live draft document.
  • Name
    lastPublishedVersionId
    Type
    UUID
    Description
    Most recently published version, if any.
  • Name
    lock
    Type
    DataContextLockState
    Description
    Current editing lock, if held — see Locking.
  • Name
    dataSources
    Type
    [DataSource!]!
    Description
    Data sources bound to this draft.
  • Name
    versions
    Type
    [DataContextVersion!]!
    Description
    All published versions.
  • Name
    latestVersion
    Type
    DataContextVersion
    Description
    Most recent published version, or null.
  • Name
    draftRevisions
    Type
    [DataContextDraftRevision!]!
    Description
    Journal of draft revisions you can roll back to.
  • Name
    project
    Type
    Project!
    Description
    Owning project.

Request

QUERY
dataContext
query DC($id: UUID!) {
  dataContext(id: $id) {
    id
    name
    revision
    schema
    lock {
      holder { userId userName }
      expiresAt
    }
    latestVersion {
      id
      number
      publishedAt
    }
  }
}

Get a published version

Returns a single immutable DataContextVersion by id.

Arguments

  • Name
    id
    Type
    UUID!
    Description
    Version identifier.

DataContextVersion fields

  • Name
    id
    Type
    UUID!
    Description
    Version identifier.
  • Name
    dataContextId
    Type
    UUID!
    Description
    Parent data context.
  • Name
    number
    Type
    Int!
    Description
    Sequential version number (starts at 1).
  • Name
    name
    Type
    String!
    Description
    Snapshot of the data context name at publish time.
  • Name
    schema
    Type
    String!
    Description
    SDL frozen at publish time.
  • Name
    designerState
    Type
    JSON
    Description
    Designer state at publish time.
  • Name
    publishedAt
    Type
    DateTime!
    Description
    When this version was published.
  • Name
    publishedBy
    Type
    User!
    Description
    Publishing user.
  • Name
    dataSources
    Type
    [DataSource!]!
    Description
    Data sources bound at publish time.

Request

QUERY
dataContextVersion
query V($id: UUID!) {
  dataContextVersion(id: $id) {
    id
    number
    name
    publishedAt
    publishedBy { id email }
  }
}

Get a draft revision

Returns one entry from a data context's draft revision journal — useful for previewing or rolling back to a specific auto-save.

Arguments

  • Name
    id
    Type
    UUID!
    Description
    Draft revision identifier.

Request

QUERY
dataContextDraftRevision
query R($id: UUID!) {
  dataContextDraftRevision(id: $id) {
    id
    revision
    capturedAt
    capturedBy { id displayName }
  }
}

Generate mock data

Runs a GraphQL query against a data context's schema and returns synthetic data shaped to match. Handy for previewing reports without hitting live sources.

Arguments

  • Name
    dataContextId
    Type
    UUID!
    Description
    Data context whose schema to use.
  • Name
    query
    Type
    String!
    Description
    A GraphQL query string to mock.
  • Name
    count
    Type
    Int
    Description
    Number of rows to generate.

Returns MockDataResult

  • Name
    data
    Type
    JSON!
    Description
    Generated rows as a JSON array.
  • Name
    rowCount
    Type
    Int!
    Description
    How many rows were returned.

Request

QUERY
mockData
query Mock($id: UUID!, $q: String!) {
  mockData(dataContextId: $id, query: $q, count: 50) {
    data
    rowCount
  }
}

Data sources

A data source is a configured connection to a database, file system, or third-party API. Data sources are referenced by data contexts.

List data sources

Arguments

  • Name
    filter.codes
    Type
    [String!]
    Description
    Filter by data source codes.
  • Name
    filter.includeDeleted
    Type
    Boolean
    Description
    When true, include soft-deleted rows. Defaults to false.
  • Name
    filter.includeInactive
    Type
    Boolean
    Description
    When true, include active: false rows. Defaults to false.
  • Name
    paging
    Type
    PagingInput
    Description
    Cursor pagination.
  • Name
    sort
    Type
    DataSourceSortingInput
    Description
    Sort by NAME or CREATED_AT.

Returns DataSourceNodesPage!.

Request

QUERY
dataSources
query {
  dataSources {
    items {
      id
      code
      name
      active
      connector { code name }
      health {
        status
        errorCode
        latencyMs
        lastCheckedAt
      }
    }
    cursor
  }
}

Get a data source

Arguments

  • Name
    id
    Type
    UUID!
    Description
    Data source identifier.

DataSource fields

  • Name
    id
    Type
    UUID!
    Description
    Identifier.
  • Name
    code
    Type
    String!
    Description
    Machine-readable code.
  • Name
    name
    Type
    String!
    Description
    Display name.
  • Name
    description
    Type
    String
    Description
    Optional description.
  • Name
    configuration
    Type
    JSON!
    Description
    Connector-specific configuration. Secret fields are returned redacted.
  • Name
    active
    Type
    Boolean!
    Description
    Whether the data source is enabled.
  • Name
    monitoringEnabled
    Type
    Boolean!
    Description
    Whether automatic health monitoring is on.
  • Name
    createdAt
    Type
    DateTime!
    Description
    Creation timestamp.
  • Name
    lastModifiedAt
    Type
    DateTime
    Description
    Last modification timestamp.
  • Name
    deletedAt
    Type
    DateTime
    Description
    Soft-deletion timestamp, or null.
  • Name
    connector
    Type
    ConnectorDefinition!
    Description
    The connector implementation.
  • Name
    health
    Type
    DataSourceHealth
    Description
    Latest health snapshot — see Subscriptions.
  • Name
    createdBy
    Type
    User!
    Description
    Creator.
  • Name
    lastModifiedBy
    Type
    User
    Description
    Last modifier.

Request

QUERY
dataSource
query DS($id: UUID!) {
  dataSource(id: $id) {
    id
    name
    configuration
    connector { code name }
    health {
      status
      latencyMs
      latencySamples {
        timestamp
        latencyMs
      }
    }
  }
}

Introspect a data source

Lists the schemas, tables, views, and functions exposed by a configured data source. Use this to discover what's available when wiring up a data context.

Arguments

  • Name
    dataSourceId
    Type
    UUID!
    Description
    Data source identifier.
  • Name
    artifactKindFilter
    Type
    String
    Description

    Limit results to a single artifact kind (e.g. TABLE, VIEW, FUNCTION).

Returns IntrospectResult with a list of ArtifactNamespaces; each namespace contains Artifacts with name, kind, fields, parameters, and returnType.

Request

QUERY
introspectDataSource
query Introspect($id: UUID!) {
  introspectDataSource(dataSourceId: $id) {
    namespaces {
      name
      artifacts {
        name
        kind
        fields {
          name
          dataType
          nullable
          primaryKey
        }
      }
    }
  }
}

Connectors

List connectors

Returns every connector implementation available to the tenant. A connector is the type of integration (e.g. Postgres, BigQuery); a data source is a configured instance of one.

ConnectorDefinition fields

  • Name
    id
    Type
    UUID!
    Description
    Connector identifier.
  • Name
    code
    Type
    String!
    Description
    Machine-readable code.
  • Name
    name
    Type
    String!
    Description
    Display name.
  • Name
    description
    Type
    String
    Description
    Optional description.
  • Name
    configSchema
    Type
    JSON
    Description
    JSON Schema describing the connector configuration.
  • Name
    active
    Type
    Boolean!
    Description
    Whether the connector is enabled.

Request

QUERY
connectors
query {
  connectors {
    id
    code
    name
    configSchema
    active
  }
}

Artifact kinds for a connector

Returns the artifact kinds (e.g. TABLE, VIEW, FUNCTION) a given connector exposes.

Arguments

  • Name
    connectorId
    Type
    UUID!
    Description
    Connector identifier.

Request

QUERY
connectorArtifactKinds
query Kinds($id: UUID!) {
  connectorArtifactKinds(connectorId: $id) {
    kind
    displayName
    description
    supportsFields
  }
}

Credits

Render operations consume credits. The credits API exposes the current balance and a paginated transaction history.

Credit balance

Returns the tenant's current credit balance.

CreditBalance fields

  • Name
    tenantId
    Type
    UUID!
    Description
    Tenant identifier.
  • Name
    balance
    Type
    Long!
    Description
    Current token balance.

Request

QUERY
creditBalance
query {
  creditBalance {
    balance
  }
}

Credit transactions

Returns paginated credit transactions for the current tenant.

Arguments

  • Name
    paging
    Type
    PagingInput
    Description
    Cursor pagination.

CreditTransaction fields

  • Name
    id
    Type
    UUID!
    Description
    Transaction identifier.
  • Name
    amount
    Type
    Long!
    Description
    Token amount — positive for top-ups, negative for usage.
  • Name
    balanceAfter
    Type
    Long!
    Description
    Balance snapshot immediately after this transaction.
  • Name
    type
    Type
    String!
    Description
    Purchase, Usage, or Adjustment.
  • Name
    description
    Type
    String
    Description
    Human-readable description.
  • Name
    externalReference
    Type
    String
    Description
    External reference (e.g. Stripe payment intent ID).
  • Name
    createdAt
    Type
    DateTime!
    Description
    When the transaction occurred.
  • Name
    userId
    Type
    UUID
    Description
    User who triggered the transaction.

Request

QUERY
creditTransactions
query {
  creditTransactions(paging: { limit: 50 }) {
    items {
      id
      amount
      balanceAfter
      type
      createdAt
    }
    cursor
  }
}

Was this page helpful?