POST /v1/workflows
Create a workflow from a graph document.
Schedule
In the graph, this is the Schedule node:summation.trigger.schedule/v1. Its own config is empty; the cadence itself lives in the request’s triggers array, alongside the graph. The node says that the workflow is scheduled, and the trigger row says when. The two halves have to agree: include the schedule trigger node exactly when the request also carries triggers, or the write is refused.
type is one of cron, interval, one_time, daily, weekly, biweekly, monthly, month_end, or yearly, with the matching fields set (days_of_week in UPPERCASE for weekly and biweekly, cron_expression for cron, every_minutes for interval).
Only schedule triggers can be created through the API today.
Playbook
In the graph, this is the Run playbook node:summation.playbook.run/v1. Config: playbook_file_id (required), params, output_ids.
Render video
In the graph, this is the Render video node:summation.video.render/v1. It turns the report the node in front of it produced into narrated MP4s, and it passes those videos on as its own artifacts, so a delivery after it sends the videos. It has its own feature gate and does not need the advanced node set: GET /v1/workflows/node-types lists it when your tenant has video rendering enabled, or has advanced workflow nodes. A graph with this node is refused with feature_not_enabled (403) on create, update, activate and run when neither is enabled. Video rendering also needs the video-spec skill to be enabled for your tenant, because the playbook writes the video spec this node renders.
Config:
Wire it between the report producer and the delivery: the producer’s
artifacts output goes to the render node’s artifacts input, and the render node’s artifacts output goes to each delivery’s artifacts input.
Delivery
Create a workflow
POST /v1/workflows
Create a workflow from a graph document.
graph is the full desired document on every write, not a patch: what you send replaces what is stored. It must contain a trigger node wired to the first work node:
playbook_file_id from GET /v1/projects/{project_id}/playbooks. The document serializes to at most 200,000 characters. Graphs authored through the API are adopted by the web editor, which normalizes them on its next save.
Activate, then run
expected_revision is optimistic concurrency: pass the revision from your last read and the write is refused if the workflow moved on in between. This matters because triggers and the graph are replace-sets: without it, two concurrent edits silently lose one.
To run one immediately, outside its schedule:
--request-id <uuid> to make a run idempotent: retry with the same value and you get the same run, not a second one. A run needs an activated version; the CLI reads activeVersionId for you when you omit --version.
Watch what happened
pending, dispatched, running, then succeeded, failed, canceled, or timed_out. Each node in the run reports its own status, and a node that never ran reads skipped with the reason it was passed over.