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 workspace gateway URL (default prod). The CLI reads FLUIDGRIDS_API_URL (or the -u/--url flag, or fluidgrids config set url); the Node and Python SDKs read FLUIDGRIDS_ENDPOINT / FLUIDGRIDS_WORKSPACE_ENDPOINT (or the baseUrl/endpoint constructor argument).

Authentication

All requests must include authentication headers:

• Authorization: Bearer <token> — platform identity token
• X-Workspace-Authorization: <workspace-token> — workspace-scoped token
• x-workspace-id: <workspace-id> — target workspace

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.

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/ready

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

• Node SDK
• Python SDK

Environment selection

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

• CLI — set FLUIDGRIDS_API_URL, pass -u/--url, or run fluidgrids config set url <endpoint>.
• Node / Python SDK — set FLUIDGRIDS_ENDPOINT (or FLUIDGRIDS_WORKSPACE_ENDPOINT), or pass the baseUrl/endpoint argument to the client constructor.

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