SDK & API Reference

This page is the complete reference for building and running Sapiom workflows. It covers two surfaces:

1. Authoring lifecycle — MCP tools (@sapiom/mcp): the customer and agent-facing surface for every step of the workflow lifecycle, from scaffolding to inspection.
2. Runtime invocation — HTTP API (apps/workflows-engine): the internal service-to-service surface used by the Sapiom platform to execute, signal, and resume workflows.

Note

New to workflows? Start with the Quickstart, then return here for the full reference.

---

Authoring lifecycle — MCP tools

The @sapiom/mcp server is the primary surface for customers and agents. Point your coding agent (Claude Code, Cursor, etc.) at it:

// .mcp.json / Claude Code MCP config
{ "command": "npx", "args": ["-y", "@sapiom/mcp"] }

All tools below are served by this MCP server and delegate to the published @sapiom/* packages.

Tool reference

Tool	Purpose	Key inputs / outputs
sapiom_authenticate	Browser-based login. Caches the credential in ~/.sapiom/credentials.json for all subsequent tools.	—
sapiom_status	Reports the current environment and authentication state.	Returns env + auth status
sapiom_logout	Clears the cached credential (sign out).	—
sapiom_dev_orchestrations_scaffold	Initialises a new workflow project with the published @sapiom/orchestration + @sapiom/tools packages.	template: "default" | "coding-pause"
sapiom_dev_orchestrations_check	Bundles index.ts, derives the manifest, and validates the step graph. Offline — no network, no spend.	Returns validation result or errors
sapiom_dev_orchestrations_run_local	Runs the full orchestration locally with every ctx.sapiom.* capability call served by stubs. Dispatched coding runs auto-resume with a stub result. Free — no real sandboxes, no spend.	Optional stubs via .sapiom-dev/stubs.json
sapiom_dev_orchestrations_link	Resolves or creates the hosted workflow definition by name (no-op if it already exists).	name → definition id
sapiom_dev_orchestrations_deploy	Mints push credentials, git pushes the current commit, triggers a cloud build, and polls until the build reaches ready. The billed unit is the execution (run), not the build.	Polls build status
sapiom_dev_orchestrations_run	Starts a real, billed cloud execution against the tenant API.	input? → executionId
sapiom_dev_orchestrations_inspect	Watches a running or completed execution — status, logs, per-step output. Also watches in-progress builds.	executionId or build id
sapiom_dev_orchestrations_signal	Resumes a paused execution (e.g. a coding-pause or human-in-the-loop gate).	executionId, name, correlationId, payload?

Tip

run_local is free; run is billed — run is the only step that starts a real (billed) cloud execution. check, run_local, and deploy don’t start a billed execution, so validate the full happy path with check + run_local before you run.

Typical lifecycle

authenticate → scaffold → check → run_local → link → deploy → run → inspect
                                                                      ↕
                                                                   signal  (if paused)

check and run_local can be repeated freely during development. deploy + run are the cloud-execution pair.

---

Runtime invocation — HTTP API

Caution

Internal / service-to-service only. Every route on this controller is guarded by ServiceKeyGuard (x-sapiom-service-key + x-sapiom-{organization,tenant,payment-account}-id identity headers). This is a Sapiom infrastructure secret — not a customer API key. Customers trigger workflows using the MCP run tool or via the x402 gateway forwarding to the engine.

A public customer-facing trigger API and webhooks are tracked in SAP-804 and are not yet available.

The runtime API is mounted at /api/workflows/* in apps/workflows-engine. All routes below require the service-key identity headers unless noted otherwise.

Trigger endpoints

Method + Path	DTO in	DTO out	Notes
POST /api/workflows/:slug/executions	ExecuteDefinitionDto	StartExecutionResponseDto	Canonical trigger. Resolves the definition by its tenant-unique slug and executes the active version. The x402 provider injects parentResumeToken for child/sub-workflow dispatch.
POST /api/workflows/workflows/:id/execute	ExecuteDefinitionDto	StartExecutionResponseDto	Trigger by definition id (M3e path). Superseded by the slug route once callers migrate.
POST /api/workflows/executions	StartExecutionDto	StartExecutionResponseDto	Legacy trigger by workflow name (build-catalog path). Superseded by the slug route.

ExecuteDefinitionDto fields (source: execute-definition.dto.ts):

Field	Type	Required	Description
input	Record<string, unknown>	No	Payload passed as the entry step’s input.
scopedApiKeyId	string	No	Per-tenant scoped-key id. Overrides the definition’s pinned key (set by the backend proxy at run time for admin-seeded definitions).
idempotencyKey	string	No	If an execution already exists with this key, the existing execution is returned instead of creating a duplicate.
parentResumeToken	string	No	HMAC-signed engine resume token forwarded by the x402 provider when this execution is a child of a parent step. Forged or expired tokens are rejected.

StartExecutionResponseDto fields (source: start-execution-response.dto.ts):

Field	Type	Description
status	"enqueued" | "already_exists"	enqueued = new execution created; already_exists = idempotency-key collision.
executionId	string	The execution’s id.
existingStatus	string (optional)	Set only when status = "already_exists" — the existing execution’s current status.

---

Signal / resume endpoint

Method + Path	DTO in	DTO out	Notes
POST /api/workflows/executions/:id/signals	SendSignalDto	SendSignalResponseDto	Resumes one or more paused executions waiting on (name, correlationId). :id frames the REST resource and scopes the lookup to the caller’s tenant.

SendSignalDto fields (source: signal.dto.ts):

Field	Type	Required	Description
name	string	Yes	Signal name the paused execution declared in pauseUntilSignal.
correlationId	string	Yes	Narrows the match to the specific waiter.
payload	Record<string, unknown>	No	Opaque JSON threaded through as the resumed step’s input.

SendSignalResponseDto:

Field	Type	Description
matched	number	Count of paused executions resumed. Normally 1 (correlation ids are expected unique per waiter) or 0 (nothing paused on that pair).

Signal / resume contract

A step pauses by returning pauseUntilSignal({ signal, resumeStep, correlationId }). The engine holds the execution until a caller fires a matching (name, correlationId) pair via this endpoint. The payload becomes the resumed step’s input.

Routing is always tenant-scoped — untrusted step code chooses its own (name, correlationId), so that pair cannot cross tenant boundaries; the firer’s tenant is the boundary (source: signal.dto.ts comment, M4).

---

Internal-only endpoints

These endpoints are service-key-gated infrastructure routes used by the platform. They are documented here for completeness; customers do not call them directly.

Method + Path	Auth	Purpose
POST /api/workflows/capability-resume	ServiceKeyGuard	The x402 gateway POSTs here when a dispatched capability (e.g. a coding run) finishes, echoing back the engine-minted resume token. The token carries the executionId; no :id param needed.
POST /api/workflows/step-events	ServiceKeyGuard	Append-only bridge: a dispatched capability forwards events it fired, correlated by the engine-minted step token. Saves events for debugging; never advances the workflow.
POST /api/workflows/dispatch/step-completion	Per-run HMAC (x-sapiom-signature + x-sapiom-timestamp)	Untrusted sandbox posts its step result here. Authenticated by a per-run HMAC over the raw body — the sandbox holds only its run’s signing secret, not the service key.
POST /api/workflows/dispatch/build-completion	Per-run HMAC (x-sapiom-signature + x-sapiom-timestamp)	Build worker posts its completion here. Same per-run HMAC auth as step-completion.

Note

The dispatch-completion routes (dispatch/step-completion and dispatch/build-completion) are on a separate controller (DispatchCompletionController) deliberately excluded from ServiceKeyGuard. The sandbox holds only a per-run signing secret — never the engine service key. The server requires rawBody: true so the HMAC covers the raw bytes, not re-serialized JSON.

---

Next steps

Authoring guide The step model, pause/resume, failure handling, and determinism — everything past the Quickstart.

Using Capabilities The full ctx.sapiom.* catalog your workflow steps can call.

Build a Workflow Scaffold, authenticate, and run your first workflow end to end.