Workflows API

About

Full lifecycle control over workflow automations from your own code: list and inspect workflows, edit drafts, promote them live, pause and resume, trigger runs against records, control in-flight runs, read performance stats, and organize workflows into folders. All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

Groups, versions, and draftsA workflow is a group of versions. At most one version is ACTIVE (live) and at most one is a DRAFT being edited. Reads return the group id used by every other workflow operation; version-level operations take a version id from getWorkflow.

Operations

Reading workflows (`READ` scope)

operationId	What it does
`listWorkflows`	List the organization’s workflow automations (paginated, non-archived by default). Returns the group id used by the other workflow operations.
`getWorkflow`	Fetch one workflow by group id — status, versions, live version, pending draft, and draft validation.
`getWorkflowVersionGraph`	Fetch one workflow version including its full node/edge graph.
`listWorkflowRuns`	List runs of one workflow version, optionally filtered by run status. Returns run ids for the run-control operations.
`getWorkflowStats`	Performance summary for one workflow (by group id) — run counts by outcome, messages sent, reply rate + sentiment split, bounce rate, last run.
`getWorkflowVersionStats`	The same summary scoped to one version — compare a new version against the one it replaced.
`listWorkflowPerformance`	Scoreboard — the org’s workflows each with headline stats (runs, active, reply rate, last run).
`getWorkflowThrottleUsage`	Daily send-limit usage for a throttle-backed workflow (`usedToday` vs `dailyCap` + history). Null for workflows with no throttle.

Building and shipping (`WRITE` scope)

operationId	What it does
`createWorkflow`	Create a workflow: a new group plus its initial DRAFT version (optionally seeded from a starter `templateId`).
`createOrReturnWorkflowDraft`	Idempotent “edit” — return the existing DRAFT, or clone the live version into a fresh DRAFT.
`updateWorkflowGraph`	Replace a DRAFT version’s node/edge graph and triggers — read the graph via `getWorkflowVersionGraph`, send back a modified copy.
`renameWorkflow`	Rename a workflow version and optionally update its description.
`promoteWorkflowDraft`	Promote the current DRAFT to ACTIVE (live). Pauses the previously-active version; optionally its in-flight runs.
`discardWorkflowDraft`	Discard the current DRAFT, if any. Idempotent.
`duplicateWorkflow`	Duplicate a workflow into a fresh group with the given name.
`deleteWorkflow`	Soft-delete a workflow (the UI’s “Delete”) — archives the group, pauses the active version, stops in-flight runs.
`applyTaskTemplate`	Instantiate a `TASK` content template against a contact: creates one real task from the template, assigned to the acting user and linked to the contact (and any `dealIds`). Title and description render the template’s merge fields and spintax against that contact, and the relative `dueOffset` resolves from now, snapped to the template’s preferred time of day. Rejects a template that isn’t type `TASK`. Get template ids from `listContentTemplates(type: TASK)`; apply each step in order to instantiate a saved checklist. See the Tasks API.

Pausing and resuming (`WRITE` scope)

operationId	What it does
`pauseWorkflow`	Pause the ACTIVE version — no new runs. `pauseInFlightRuns` also pauses runs already in flight.
`resumeWorkflow`	Resume the most-recently-paused version. No-op if a version is already active.
`resumeWorkflowVersion`	Resume a specific PAUSED version (roll back to an older version); pauses the active sibling first.

Run control (`WRITE` scope)

operationId	What it does
`triggerWorkflowRun`	Manually start one run of the ACTIVE version against a record (contact/property/deal/task id per the workflow’s domain).
`pauseWorkflowRun`	Pause one in-flight run (PENDING/RUNNING → PAUSED).
`resumeWorkflowRun`	Resume one paused run (PAUSED → PENDING).
`stopWorkflowRun`	Permanently stop one run (terminal).
`bulkPauseWorkflowRuns`	Pause many runs at once by explicit id (cap 500); ineligible ids are counted in `skippedCount`.
`bulkResumeWorkflowRuns`	Resume many paused runs at once by explicit id (cap 500).

Folders (`READ` + `WRITE` scope)

Folders are a tree: each has an id, a name, a parentFolderId (null at the root) and a displayOrder. Every folder operation addresses folders by id.

operationId	Scope	What it does
`listWorkflowFolders`	`READ`	List the organization’s workflow-folder tree — `id`, `name`, `parentFolderId`, `displayOrder`, `itemCount`.
`createWorkflowFolder`	`WRITE`	Create an empty folder, optionally nested under `parentFolderId`; returns its id.
`moveWorkflowToFolder`	`WRITE`	Move a workflow (by its group id) into a folder by `folderId` (`null` to ungroup).
`moveWorkflowFolder`	`WRITE`	Move a folder under another folder, or pass `parentFolderId: null` to move it to the root.
`renameWorkflowFolder`	`WRITE`	Rename a folder by `folderId`.
`deleteWorkflowFolder`	`WRITE`	Delete a folder by `folderId` (its workflows become ungrouped).
`reorderWorkflowFolders`	`WRITE`	Persist a new display order for the folders that share one parent — pass `parentFolderId` (`null` for the root) and the ordered `folderIds`.

Organization guardWorkflow operations are org-guarded on the ids you pass — a workflowId, folderId, or content-template id from another organization returns 403 forbidden. Listing and creating happen under your own org. See Authorization for the model.

Example

Trigger the live version of a workflow against one contact:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "triggerWorkflowRun", "variables": { "workflowGroupId": "GROUP_ID", "recordId": "CONTACT_ID" } }'

Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.

Getting Started

TypeScript SDK

Core Resources

Automations

Communication & Tasks

Account & Billing

About

Operations

Reading workflows (`READ` scope)

Building and shipping (`WRITE` scope)

Pausing and resuming (`WRITE` scope)

Run control (`WRITE` scope)

Folders (`READ` + `WRITE` scope)

Example

​About

​Operations

​Reading workflows (READ scope)

​Building and shipping (WRITE scope)

​Pausing and resuming (WRITE scope)

​Run control (WRITE scope)

​Folders (READ + WRITE scope)

​Example

About

Operations

Reading workflows (`READ` scope)

Building and shipping (`WRITE` scope)

Pausing and resuming (`WRITE` scope)

Run control (`WRITE` scope)

Folders (`READ` + `WRITE` scope)

Example