API and local runner
Automate Xentropy workflow tests with the HTTP API and local Node.js runner. Configure scoped credentials, export graphs, and inspect run results.
The platform owns service definitions, DAGs, cases and run history. Workflows execute in a browser or the local runner. No API accepts a command to execute the whole workflow in a sandbox.
Access
Use a Clerk session JWT for browser management. From Local access, create a runner token scoped to a saved workflow. It expires after 30 days and can be revoked. Its plaintext is shown once. Keep it in XENTROPY_RUNNER_TOKEN, never in a graph or context file. Use XENTROPY_API_URL for the platform origin. Requests carry Authorization: Bearer TOKEN.
node xentropy-runner.mjs workflow.json
node xentropy-runner.mjs workflow.json test-case-id
node xentropy-runner.mjs --resume RUN_ID
Download the runner from /resources/xentropy-runner.mjs, or use npm run graph:run -- before these arguments. Node.js 24+ is required. Save the workflow before exporting it for a scoped runner; it executes the exact saved revision. The CLI prints actual results and returns a nonzero status for a failed suite. Ctrl-C cancels the run.
Routes
All paths use /v1/graph.
| Method/path | Behavior |
|---|---|
GET /capabilities | Public auth configuration, model, prices and limits |
GET /workflows | List saved workflow definitions |
POST /workflows | Save a validated workflow and allocate its next revision |
GET /workflows/:id | Read a saved workflow |
POST /runs | Start `{workflow,testCaseId,location:"browser" |
GET /runs | Recent account runs |
GET /runs/:id | Immutable run input and current results |
PUT /runs/:id/nodes/:nodeId | Record a client-reported real-node observation |
POST /runs/:id/heartbeat | Renew runner presence |
POST /runs/:id/finish | Finish with passed, failed, cancelled or interrupted status |
POST /runs/:id/cancel | Cancel pending simulations and release session state |
POST /runs/:id/invocations | Submit {nodeId,input} with Idempotency-Key |
GET /runs/:id/invocations/:id | Poll the hosted simulation result |
GET /tokens | Inspect runner credentials without their secrets |
POST /tokens | Create {name,workflowId?} credential; human authentication required |
DELETE /tokens/:id | Revoke a credential |
Simulation statuses distinguish queued, running, completed, failed, cancelled and indeterminate. An indeterminate dispatch is not retried automatically. Preserve the same key for the same logical invocation; changing its input is a conflict. Real HTTP calls are never automatically retried.
Graph format
A workflow contains id, numeric revision, name, services, nodes and tests. Each service supplies instructions, selected files, operations and initial state. Multiple nodes may reference one service instance ID to share state within the run.
A node references serviceId, operationId, instanceId, mode, dependsOn, input and bindings. Bindings use {target,source,path} where target/path are JSON Pointers and source is $input or an upstream node ID. Every node binding must have an explicit dependency edge. Real nodes configure real.url, method, optional non-secret headers and secretHeaders mapping header names to local environment variable names. Browser execution refuses local secret references.
Cases include an ID, name, input, assertions and optional terminal nodes, initial state, scenarios and mode overrides. Assertions stay outside agent context. The editor and shared model validator describe the supported schema subset; unsupported schema features fail validation instead of being silently ignored.
One run is one session. Each case starts fresh simulated state; real-service state remains external. Completed history is evidence, not state to seed a later case. Simulated results are server-owned; real results are explicitly client-reported.