> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goliathdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Workflows API
> Create, edit, promote, and control workflow automations and their runs through the Goliath developer 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](/developer-api/overview).
**Groups, versions, and drafts**
A 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](/developer-api/tasks). |
### 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 guard**
Workflow 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](/developer-api/authorization) for the model.
## Example
Trigger the live version of a workflow against one contact:
```bash theme={null}
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](/developer-api/overview#discovering-operations).