API Reference

FluidGrids provides comprehensive APIs for programmatic access. The primary API is GraphQL; a limited REST API is available for specific operations.

GraphQL API

The GraphQL API is the primary interface for all FluidGrids operations.

Endpoints

Environment	Workspace Gateway	Global Gateway
`prod` (default)	`https://graphqlworkspaces.burdenoff.com/workspaces/graphql`	`https://graphql.burdenoff.com/global/graphql`
`alpha`	`https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql`	`https://alphagraphql.burdenoff.com/global/graphql`
`local`	`http://localhost:4003/workspaces/graphql`	`http://localhost:4000/global/graphql`

Point your client directly at the appropriate gateway URLs (default prod). The CLI, the Node SDK and the MCP server read FLUIDGRIDS_WORKSPACE_ENDPOINT and FLUIDGRIDS_GLOBAL_ENDPOINT; the Node SDK also takes workspaceEndpoint / globalEndpoint in its constructor. See GraphQL API for the headers every request needs, including Origin.

Authentication

All requests must include authentication headers:

Authorization: Bearer <token> — platform identity token
X-Workspace-Authorization: Bearer <workspace-token> — workspace-scoped token
x-workspace-id: <workspace-id> — target workspace (optional when the workspace token is sent)
Origin: https://app.fluidgrids.ai — required from server-side clients; see GraphQL API

Example query

List the latest version of every workflow in the workspace:

query ListWorkflows {
  workflowDefinitions(input: { latestOnly: true, limit: 20 }) {
    items {
      id
      name
      workflowKey
      version
      status
      isActive
      totalVersions
    }
    total
    hasMore
  }
}

Example mutation

Trigger a workflow version through its manual trigger node:

mutation TriggerWorkflow {
  triggerWorkflow(
    input: {
      workflowKey: "order-to-cash"
      version: "3"
      triggerNodeId: "trigger-1"
      triggerData: { orderId: "ORD-12345" }
    }
  ) {
    runId
    status
    version
  }
}

Other frequently used operations: activateWorkflowDefinition, restoreWorkflowVersion, duplicateWorkflow, importWorkflowTemplate, cancelWorkflowRun, pauseWorkflowRun, resumeWorkflowRun, retryNode, workflowRun, and workflowRunLogs. The full schema is what the CLI and SDKs are generated from.

REST API

GraphQL is the primary API for all workflow operations. REST is limited to a small set of endpoints — inbound webhook triggers and service health checks. There is no general-purpose REST CRUD API; use GraphQL for everything else. The full list of HTTP endpoints and their responses is in REST API, and webhook authentication is in Webhooks.

Webhook triggers

Trigger a workflow that starts with a Webhook trigger node by POSTing to its webhook token:

POST https://graphqlworkspaces.burdenoff.com/api/webhooks/t/{webhookToken}
Content-Type: application/json

{
  "payload": { "key": "value" }
}

Related webhook endpoints:

POST https://graphqlworkspaces.burdenoff.com/api/webhooks/resume/{runId} — resume a run that is paused at a Wait node
POST https://graphqlworkspaces.burdenoff.com/api/webhooks/trigger/{name}/ — trigger a workflow by its named webhook route

Health check

GET /health
GET /health/ready

Both return 200 OK when the service is up. (/ready alone is not a valid path — it returns 404.)

Rate limiting

Per-tier request quotas are not currently enforced, and any published limits are subject to change — do not design integrations against a specific rate cap. When rate limiting is enabled, responses will carry standard headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1623456789

Error codes

Code	Meaning
`VALIDATION_ERROR`	Invalid input
`AUTHENTICATION_ERROR`	Missing or invalid token
`AUTHORIZATION_ERROR`	Insufficient permissions
`NOT_FOUND`	Resource does not exist
`RATE_LIMITED`	Too many requests
`INTERNAL_ERROR`	Server-side failure

SDKs

Environment selection

API clients target an environment by pointing at that environment's workspace gateway URL (see Endpoints); the default is prod.

CLI and MCP server — set FLUIDGRIDS_WORKSPACE_ENDPOINT and FLUIDGRIDS_GLOBAL_ENDPOINT (the CLI also needs FLUIDGRIDS_OIDC_ISSUER for alpha sign-in).
Node SDK — set the same variables, or pass workspaceEndpoint / globalEndpoint to the constructor.

BURDENOFF_ENV is read only by the browser and VS Code extensions; it has no effect on the CLI or SDKs.

GraphQL API​

Endpoints​

Authentication​

Example query​

Example mutation​

REST API​

Webhook triggers​

Health check​

Rate limiting​

Error codes​

SDKs​

Environment selection​