Node SDK

@fluidgrids/sdk is the official TypeScript SDK for FluidGrids. It covers the FluidGrids workflow surface (workflows, runs, nodes, credentials, webhooks, scheduled jobs) and the shared platform modules (auth, workspaces, organisations, tags, files, billing, notifications, support and more) in one typed client. It needs Node.js 24.11 or later (or Bun 1.3.14 or later) and works as an ES module or from CommonJS.

Install

npm install @fluidgrids/sdk
# or
bun add @fluidgrids/sdk

Quick start

import { FluidGridsSDK } from '@fluidgrids/sdk';

const sdk = new FluidGridsSDK({
  accessToken: process.env.FG_ACCESS_TOKEN,
  refreshToken: process.env.FG_REFRESH_TOKEN,
});

// Workspace calls need a workspace token as well as the platform token.
await sdk.auth.issueWorkspaceToken(workspaceId, organizationId);

const page = await sdk.fluidgrids.workflows.list({ status: 'ACTIVE', limit: 20 });
console.log(page.items.map((workflow) => workflow.workflowKey));

const run = await sdk.fluidgrids.workflows.trigger({
  workflowKey: 'invoice-sync',
  version: '1.0.0',
  triggerNodeId: 'start',
  triggerData: { amount: 42 },
  idempotencyKey: 'invoice-sync-2026-10-21',
});

const finished = await sdk.fluidgrids.runs.waitForCompletion(run.runId, { timeout: 600_000 });
const logs = await sdk.fluidgrids.runs.logs(run.runId, { minLevel: 'WARN' });

idempotencyKey makes a retried trigger return the original run instead of starting another one.

Signing in

The SDK never asks for a password. Get tokens with one of the sdk.auth flows:

Flow	Use it for	Methods
Device code	Scripts and tools a person runs: the user approves a code in their browser	loginWithDeviceCode() returns { userCode, verificationUri, promise }
PKCE	Your own app that signs users in	buildAuthorizationUrl(), then exchangeAuthCode(code, codeVerifier)
Client credentials	Automation acting as an app, with no user	loginWithClientCredentials(clientId, clientSecret)

Register apps and create their credentials under Developer Portal in the app. Then call issueWorkspaceToken(workspaceId, organizationId) for the workspace you act in; fetchWorkspaces() lists the ones available to you. With autoRefresh (on by default) the SDK refreshes the access token before it expires and calls onTokenRefresh with the new pair so you can store it.

Configuration

Option	Environment variable	Default
workspaceEndpoint	FLUIDGRIDS_WORKSPACE_ENDPOINT	https://graphqlworkspaces.burdenoff.com/workspaces/graphql
globalEndpoint	FLUIDGRIDS_GLOBAL_ENDPOINT	https://graphql.burdenoff.com/global/graphql
productOrigin	FLUIDGRIDS_ORIGIN	https://app.fluidgrids.ai for production, https://alphaapp.fluidgrids.ai for alpha

For alpha, point both endpoints at the alpha gateways (https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql and https://alphagraphql.burdenoff.com/global/graphql). The workflow operations are product-scoped and the gateway works out the product from the request's Origin, which Node does not send by itself; the SDK sets it for the production and alpha gateways. Set productOrigin only if you use another gateway.

Other options: timeout (per request, in milliseconds), signal (an AbortSignal for every request), logLevel or your own logger, and tokenStore to keep tokens somewhere other than memory.

The FluidGrids module

Namespace	Operations
fluidgrids.workflows	list, get({ id } | { workflowKey, version }), versions, create, update, delete, trigger, publish, activate, deactivate, archive, duplicate, importTemplate
fluidgrids.runs	list, get, logs, cancel, pause, resume, retryNode(runId, nodeId), waitForCompletion
fluidgrids.nodes	list, get(nodeType, nodeVersion)
fluidgrids.credentials	list, get, listTypes, create, authenticateWithApiKey, authenticateWithBasicAuth, update, delete, test
fluidgrids.webhooks	list, get, create, update, delete, toggle
fluidgrids.scheduledJobs	list, get, create, update, delete, setEnabled
fluidgrids.dashboard	summary, usage({ startDate, endDate })
fluidgrids.search	search, byEntityType
fluidgrids.admin	systemInfo

List methods return { items, total, hasMore } and take limit and offset. A credential is an integration connection and is created in two steps: create (no secret material), then authenticateWithApiKey or authenticateWithBasicAuth. Every type (FluidgridsWorkflow, FluidgridsRun, FluidgridsTriggerWorkflowInput, …) is exported from @fluidgrids/sdk.

Each call is permission-checked against your roles; see Permissions and Access Control.

Errors

Failed calls throw typed errors you can catch by class:

import {
  AuthenticationError,
  AuthorizationError,
  FluidGridsError,
  RateLimitError,
  ValidationError,
} from '@fluidgrids/sdk';

try {
  await sdk.fluidgrids.workflows.trigger({ workflowKey: 'invoice-sync', version: '1.0.0', triggerNodeId: 'start' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // sign in again
  } else if (error instanceof AuthorizationError) {
    // your role lacks the permission
  } else if (error instanceof RateLimitError) {
    // back off; a plan quota or a rate limit was hit
  } else if (error instanceof ValidationError || error instanceof FluidGridsError) {
    console.error(error.message);
  }
}

Next steps

• CLI Reference
• GraphQL API
• Examples