references/graph-schema.md
Workflow graph schema
The contract for actions and edges. The stored workflow is loose JSON, but the visual editor validates every node against a strict schema keyed on type. A node that saves successfully but doesn't match this contract will break the editor view for the whole workflow when someone opens it. Treat the shapes below as required, not advisory.
Contents
- Node (action) shape
- Action types and their
config - Edges
function*inputs- Duration strings (
delay_duration,max_wait_duration) - Waiting until a date (
delay_until) - Conversion & exit condition
- Pre-submit checklist
Node (action) shape
Every action object has these common fields plus a type-specific config:
{
"id": "unique_within_workflow",
"name": "Human label",
"description": "",
"type": "<see action types>",
"config": {},
"on_error": "continue",
"filters": null,
"output_variable": null
}
id— unique within the workflow; edges reference it byfrom/to.on_error— optional; onlycontinueorabort. Omit to use the default.filters— optional property filters gating the action:{properties: [<cond>]}. Sendproperties, notbytecode.output_variable— optional; store a step result into a workflow variable.{key, result_path?, spread?}.
Action types and their config
Use only these type values — they are the complete supported set. An unknown or unsupported type breaks the editor's parse for the entire graph.
| type | config |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| trigger | a trigger config (see below). Exactly one trigger node per workflow. |
| delay | { "delay_duration": "30m" }, or { "delay_until": {"expression": "<HogQL date>", "offset?": "-1d"}, "max_delay_duration?": "30d" } to wait for a per-person date. Exactly one of the two. See duration rules and delay_until below. |
| conditional_branch | { "conditions": [ { "filters": {"properties": [<cond>]}, "name?": "" } ] }. Index N pairs with the branch edge index: N. |
| random_cohort_branch | { "cohorts": [ { "percentage": 50, "name?": "A" } ] }. Percentages are relative weights and should sum to 100, but a total above or below 100 still splits traffic in the given proportions. |
| wait_until_condition | { "condition?": {"filters": {"properties": [<cond>]}}, "events?": [{"filters": {...}, "name?": ""}], "max_wait_duration": "7d" }. condition is optional: an events-only wait is valid (server seeds a missing condition as {filters: null}). Duration rules as delay. |
| wait_until_time_window | { "timezone": "UTC", "use_person_timezone?": false, "day": <"weekday" / "weekend" / "any" / ["monday",...]>, "time": <"any" / ["10:00","11:00"]> }. |
| function | { "template_id": "<live template id>", "inputs": { ... }, "mappings?": [] }. Don't guess the id or its inputs — discover them live (see below). |
| function_email | { "template_id?": "template-email", "template_uuid?": "<saved template UUID>", "inputs": {"email": {"value": {...}}}, "message_category_type?": <"marketing" / "transactional">, "tracking_enabled?": <bool> }. template_id is the literal template-email; omit it and the server infers it from the step type. Reference a saved library template (from workflows-list-email-templates) by putting its UUID in template_uuid, never in template_id — a UUID sent as template_id is moved into template_uuid automatically. When template_uuid is set and the value has no body keys (subject/text/html/design), the server copies the template's body into inputs.email.value at save (a snapshot — later template edits don't propagate); you still supply from and to. Set from to {integrationId: <sender id>} for one sender. To rotate across up to 10 senders, also set integrationIds: [<sender id>, ...]; keep integrationId as the first sender for compatibility. Workflow runs using the same sender list resolve to the same sender, including across multiple email steps. If you author any body key inline, your body wins and template_uuid is provenance only. tracking_enabled defaults to true; when false, no open pixel is injected and links are not rewritten, so opens/clicks are not recorded for this step (delivery/bounce/unsubscribe still are). |
| function_sms | { "template_id?": "template-twilio", "inputs": { ... }, "message_category_type?": "..." }. template_id is the literal template-twilio; omit it and the server infers it. |
| function_push | { "template_id?": "template-native-push", "inputs": { ... }, "message_category_type?": <"marketing" / "transactional"> }. template_id is the literal template-native-push; omit it and the server infers it. Sends a mobile push notification via FCM/APNs. Its inputs are richer than email's — title, body, and a channels list of the FCM/APNs integration ids to send through — so retrieve the template-native-push inputs_schema (as with function) for the exact keys, and use the project's push integration ids for channels. |
| exit | { "reason?": "Done" }. Usually one terminal exit node. |
Branch and wait condition filters (the filters wrapper is mandatory)
conditional_branch and wait_until_condition gate on a filters object, the action-filter shape ({properties?, events?, actions?, source?, filter_test_accounts?}). The wrapper is not optional:
- Write
{ "filters": { "properties": [<cond>] } }on each condition, never{ "properties": [<cond>] }directly on the condition object. The bare form saves but the visual editor flags it and the branch compiles to a constant, so it never evaluates your condition. conditional_branchconditions are property-only (person/group<cond>s). Event/action filters are rejected here ("Event filters are not allowed in conditionals").wait_until_conditionis event-aware: itscondition.filtersand eachevents?[].filtersmay also carryevents/actions. An entry naming neither an event nor an action is dropped (it would match everything).sourceis optional (defaults toevents). Never sendbytecode; the server compiles it fromproperties.
Trigger config (the trigger node)
Discriminated on config.type:
event—{ "type": "event", "filters": { "events": [{ "id": "<event>", "name": "<event>", "type": "events", "order": 0, "properties": [<cond>] }], "properties": [<cond>], "filter_test_accounts": false } }. Fires on every matching occurrence. Throttle repeats withtrigger_masking(dedup/sampling — not behavioral filtering).webhook/manual/tracking_pixel—{ "type": "webhook", "template_id": "<literal>", "inputs": { ... } }. These use a fixed built-in source template, not one you look up:template-source-webhookfor bothwebhookandmanual,template-source-webhook-pixelfortracking_pixel. Omitting or guessing it fails the create withTemplate not foundagainst the trigger node. They aresource_webhooktemplates and are not in the destination catalog (cdp-function-templates-lististype=destination), so don't try to discover them there. Each needsinputs.eventandinputs.distinct_idwrapped in{value: ...}, and the right values differ per trigger type because a different request reaches the template:webhook— a POST whose body you control:"inputs": { "event": { "value": "{request.body.event}" }, "distinct_id": { "value": "{request.body.distinct_id}" } }.manual— the "trigger manually" button POSTs{user_id, $variables}, so the body carries noevent: use the fixed literal"inputs": { "event": { "value": "$workflow_triggered" }, "distinct_id": { "value": "{request.body.user_id}" } }. Pointingeventat{request.body.event}here makes every manual run return 400 (the source template rejects an emptyevent) while the UI still shows a success toast, so the workflow silently never fires.tracking_pixel— a bodylessGET, so read query params:"inputs": { "event": { "value": "{request.query.ph_event}" }, "distinct_id": { "value": "{request.query.ph_distinct_id}" } }. Body references resolve empty here and the pixel still returns its 200 GIF, so every hit is dropped with no error to retry on.
batch—{ "type": "batch", "filters": { "properties": [<cond>] } }. The audience: person-property conditions and/or cohort references. No event/action filters (silently dropped, so rejected). Does not fire on enable — dispatch a one-off broadcast withworkflows-run-batch, or make it recurring withworkflows-schedule-create(attaches an RRULE schedule; each firing re-broadcasts to this sameconfig.filters.propertiesaudience). A recurring broadcast is abatchtrigger plus a schedule. Editingconfig.filterspauses any schedule attached to it, since the confirmed recipient count no longer holds - preview again and re-create the cadence.schedule—{ "type": "schedule" }. One person-less run per occurrence, for jobs that act on their own (for example a "Create AI task" step). Attach the cadence withworkflows-schedule-create; no audience preview is needed. Changing this trigger tobatchpauses any schedule already attached, because that cadence was never sized against an audience - re-create it after the blast-ra