@epilot/sdk 2.20.85 → 2.20.87

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/definitions/automation-runtime.json +1 -1
  2. package/definitions/automation.json +294 -17
  3. package/definitions/workflow-definition.json +686 -12
  4. package/definitions/workflow-runtime.json +1 -1
  5. package/definitions/workflow.json +4072 -1386
  6. package/dist/apis/access-token.cjs +6 -6
  7. package/dist/apis/access-token.js +1 -1
  8. package/dist/apis/address-suggestions.cjs +6 -6
  9. package/dist/apis/address-suggestions.js +1 -1
  10. package/dist/apis/address.cjs +6 -6
  11. package/dist/apis/address.js +1 -1
  12. package/dist/apis/ai-agents.cjs +6 -6
  13. package/dist/apis/ai-agents.js +1 -1
  14. package/dist/apis/app.cjs +6 -6
  15. package/dist/apis/app.js +1 -1
  16. package/dist/apis/audit-logs.cjs +6 -6
  17. package/dist/apis/audit-logs.js +1 -1
  18. package/dist/apis/automation.cjs +8 -8
  19. package/dist/apis/automation.d.cts +2 -2
  20. package/dist/apis/automation.d.ts +2 -2
  21. package/dist/apis/automation.js +2 -2
  22. package/dist/apis/billing.cjs +6 -6
  23. package/dist/apis/billing.js +1 -1
  24. package/dist/apis/blueprint-manifest.cjs +6 -6
  25. package/dist/apis/blueprint-manifest.js +1 -1
  26. package/dist/apis/calendar.cjs +6 -6
  27. package/dist/apis/calendar.js +1 -1
  28. package/dist/apis/chat.cjs +6 -6
  29. package/dist/apis/chat.js +1 -1
  30. package/dist/apis/configuration-hub.cjs +6 -6
  31. package/dist/apis/configuration-hub.js +1 -1
  32. package/dist/apis/consent.cjs +6 -6
  33. package/dist/apis/consent.js +1 -1
  34. package/dist/apis/customer-portal.cjs +6 -6
  35. package/dist/apis/customer-portal.js +1 -1
  36. package/dist/apis/dashboard.cjs +6 -6
  37. package/dist/apis/dashboard.js +1 -1
  38. package/dist/apis/data-governance.cjs +6 -6
  39. package/dist/apis/data-governance.js +1 -1
  40. package/dist/apis/deduplication.cjs +6 -6
  41. package/dist/apis/deduplication.js +1 -1
  42. package/dist/apis/design.cjs +6 -6
  43. package/dist/apis/design.js +1 -1
  44. package/dist/apis/document.cjs +6 -6
  45. package/dist/apis/document.js +1 -1
  46. package/dist/apis/email-settings.cjs +6 -6
  47. package/dist/apis/email-settings.js +1 -1
  48. package/dist/apis/email-template.cjs +6 -6
  49. package/dist/apis/email-template.js +1 -1
  50. package/dist/apis/entity-mapping.cjs +6 -6
  51. package/dist/apis/entity-mapping.js +1 -1
  52. package/dist/apis/entity.cjs +6 -6
  53. package/dist/apis/entity.js +1 -1
  54. package/dist/apis/environments.cjs +6 -6
  55. package/dist/apis/environments.js +1 -1
  56. package/dist/apis/event-catalog.cjs +6 -6
  57. package/dist/apis/event-catalog.js +1 -1
  58. package/dist/apis/external-values.cjs +6 -6
  59. package/dist/apis/external-values.js +1 -1
  60. package/dist/apis/file.cjs +6 -6
  61. package/dist/apis/file.js +1 -1
  62. package/dist/apis/iban.cjs +6 -6
  63. package/dist/apis/iban.js +1 -1
  64. package/dist/apis/identity.cjs +6 -6
  65. package/dist/apis/identity.js +1 -1
  66. package/dist/apis/integration-toolkit.cjs +6 -6
  67. package/dist/apis/integration-toolkit.js +1 -1
  68. package/dist/apis/journey.cjs +6 -6
  69. package/dist/apis/journey.js +1 -1
  70. package/dist/apis/kanban.cjs +6 -6
  71. package/dist/apis/kanban.js +1 -1
  72. package/dist/apis/message.cjs +6 -6
  73. package/dist/apis/message.js +1 -1
  74. package/dist/apis/metering.cjs +6 -6
  75. package/dist/apis/metering.js +1 -1
  76. package/dist/apis/notes.cjs +6 -6
  77. package/dist/apis/notes.js +1 -1
  78. package/dist/apis/notification.cjs +6 -6
  79. package/dist/apis/notification.js +1 -1
  80. package/dist/apis/organization.cjs +6 -6
  81. package/dist/apis/organization.js +1 -1
  82. package/dist/apis/partner-directory.cjs +6 -6
  83. package/dist/apis/partner-directory.js +1 -1
  84. package/dist/apis/permissions.cjs +6 -6
  85. package/dist/apis/permissions.js +1 -1
  86. package/dist/apis/phone-integration.cjs +6 -6
  87. package/dist/apis/phone-integration.js +1 -1
  88. package/dist/apis/pricing-tier.cjs +6 -6
  89. package/dist/apis/pricing-tier.js +1 -1
  90. package/dist/apis/pricing.cjs +6 -6
  91. package/dist/apis/pricing.js +1 -1
  92. package/dist/apis/purpose.cjs +6 -6
  93. package/dist/apis/purpose.js +1 -1
  94. package/dist/apis/query.cjs +6 -6
  95. package/dist/apis/query.js +1 -1
  96. package/dist/apis/sandbox.cjs +6 -6
  97. package/dist/apis/sandbox.js +1 -1
  98. package/dist/apis/sharing.cjs +6 -6
  99. package/dist/apis/sharing.js +1 -1
  100. package/dist/apis/snapshot.cjs +6 -6
  101. package/dist/apis/snapshot.js +1 -1
  102. package/dist/apis/submission.cjs +6 -6
  103. package/dist/apis/submission.js +1 -1
  104. package/dist/apis/target.cjs +6 -6
  105. package/dist/apis/target.js +1 -1
  106. package/dist/apis/targeting.cjs +6 -6
  107. package/dist/apis/targeting.js +1 -1
  108. package/dist/apis/template-variables.cjs +6 -6
  109. package/dist/apis/template-variables.js +1 -1
  110. package/dist/apis/user.cjs +6 -6
  111. package/dist/apis/user.js +1 -1
  112. package/dist/apis/validation-rules.cjs +6 -6
  113. package/dist/apis/validation-rules.js +1 -1
  114. package/dist/apis/webhooks.cjs +6 -6
  115. package/dist/apis/webhooks.js +1 -1
  116. package/dist/apis/workflow-definition.cjs +6 -6
  117. package/dist/apis/workflow-definition.d.cts +2 -2
  118. package/dist/apis/workflow-definition.d.ts +2 -2
  119. package/dist/apis/workflow-definition.js +1 -1
  120. package/dist/apis/workflow.cjs +8 -8
  121. package/dist/apis/workflow.d.cts +2 -2
  122. package/dist/apis/workflow.d.ts +2 -2
  123. package/dist/apis/workflow.js +2 -2
  124. package/dist/automation-KNJZDJD7.cjs +7 -0
  125. package/dist/automation-RKVFGJTO.js +7 -0
  126. package/dist/{automation-runtime-KLCXZKEC.cjs → automation-runtime-7LXZ343U.cjs} +2 -2
  127. package/dist/{automation-runtime-Y52HM57N.js → automation-runtime-JZKABTGP.js} +1 -1
  128. package/dist/{automation.d-B8g3nYp-.d.cts → automation.d-cTvIBxDI.d.cts} +514 -26
  129. package/dist/{automation.d-B8g3nYp-.d.ts → automation.d-cTvIBxDI.d.ts} +514 -26
  130. package/dist/{chunk-7T4BNWMN.js → chunk-AMLTCPBT.js} +5 -5
  131. package/dist/{chunk-WOUASZJW.cjs → chunk-EIT2JFPB.cjs} +1 -1
  132. package/dist/{chunk-QW3ROE6H.js → chunk-JKCBMHOZ.js} +1 -1
  133. package/dist/{chunk-ZSZ4IWLQ.cjs → chunk-PQONAXAH.cjs} +5 -5
  134. package/dist/chunk-SWEH4LP3.cjs +14 -0
  135. package/dist/chunk-W5OQ3L53.js +14 -0
  136. package/dist/index.cjs +12 -12
  137. package/dist/index.d.cts +3 -3
  138. package/dist/index.d.ts +3 -3
  139. package/dist/index.js +3 -3
  140. package/dist/workflow-B5IJTSPX.js +7 -0
  141. package/dist/workflow-GOWWDU4Y.cjs +7 -0
  142. package/dist/workflow-definition-46NTR2N5.cjs +7 -0
  143. package/dist/workflow-definition-BSY2BNM2.js +7 -0
  144. package/dist/{workflow-definition.d-CweGhhBU.d.ts → workflow-definition.d-Be0CM3Py.d.cts} +574 -10
  145. package/dist/{workflow-definition.d-CweGhhBU.d.cts → workflow-definition.d-Be0CM3Py.d.ts} +574 -10
  146. package/dist/{workflow-runtime-L5HMFISV.js → workflow-runtime-GPXNF7WI.js} +1 -1
  147. package/dist/{workflow-runtime-LMGACZP4.cjs → workflow-runtime-HD6U5ZSL.cjs} +2 -2
  148. package/dist/workflow.d-B7utaxgb.d.cts +6868 -0
  149. package/dist/workflow.d-B7utaxgb.d.ts +6868 -0
  150. package/docs/automation.md +267 -26
  151. package/docs/workflow-definition.md +840 -138
  152. package/docs/workflow.md +4537 -1746
  153. package/package.json +1 -1
  154. package/dist/automation-G2CKAQNB.cjs +0 -7
  155. package/dist/automation-UPTNUOYO.js +0 -7
  156. package/dist/chunk-522LYPPW.js +0 -14
  157. package/dist/chunk-PM25LLET.cjs +0 -14
  158. package/dist/workflow-JQT3F5NJ.cjs +0 -7
  159. package/dist/workflow-Q6FAE5OL.js +0 -7
  160. package/dist/workflow-definition-MSO4JDA3.js +0 -7
  161. package/dist/workflow-definition-XTWO4RMY.cjs +0 -7
  162. package/dist/workflow.d-5cyNJgVQ.d.cts +0 -3843
  163. package/dist/workflow.d-5cyNJgVQ.d.ts +0 -3843
@@ -37,6 +37,14 @@ declare namespace Components {
37
37
  * requirements that need to be fulfilled in order to enable the task while flow instances are running
38
38
  */
39
39
  requirements?: /* describe the requirement for a task to be enabled */ EnableRequirement[];
40
+ /**
41
+ * When true, the task is required and users cannot skip it while the flow is running. Unrelated to `requirements`, which gate when a task becomes enabled. System-driven skips are unaffected — tasks on a not-taken decision branch, and automation tasks whose automation execution itself reports a skipped verdict (e.g. unmet trigger conditions). Only a manual task, or an automation or AI task whose `trigger_mode` is `manual` or absent, can carry it: on a decision or an automatic kind it is normalised to false on create, update and load.
42
+ */
43
+ required?: boolean;
44
+ /**
45
+ * Checklist items from the task's party descriptions, derived by the server from the checklist markup (`ul[__lexicallisttype="check"] > li[data-subtask-id]`, nearest list ancestor) on every create, update and load — a client-supplied array is replaced. Parties are read in the order description, ecp, installer, partner and the first occurrence of an id wins; an id occurring twice in one task is rejected. An item is required only when it is marked `data-subtask-required="true"` in the markup, the task kind has a person action (a manual task, a decision with `trigger_mode: manual`, or an automation or AI task whose `trigger_mode` is `manual` or absent) and it lives in the co-worker or partner description. Required items gate task completion while the flow is running.
46
+ */
47
+ subtasks?: /* One checklist item of a task, derived from the checklist markup in the party descriptions. Identity is the stable data-subtask-id the editor mints into the markup. */ Subtask[];
40
48
  assigned_to?: (string | /* Represents a variable assignment with its expression and optional resolved value. Used for dynamic user assignments that get resolved during workflow execution. */ VariableAssignment)[];
41
49
  ecp?: /* Details regarding ECP for the workflow step */ ECPDetails;
42
50
  installer?: /* Details regarding ECP for the workflow step */ ECPDetails;
@@ -48,6 +56,43 @@ declare namespace Components {
48
56
  phase_id?: string;
49
57
  task_type: TaskType;
50
58
  agent_config?: /* Configuration for AI Agent to run */ AgentConfig;
59
+ /**
60
+ * How the agent run is started. `automatic` starts it as soon as the task becomes current; `manual` waits for a person to run it and to approve the result. An absent value is read as `manual` everywhere: the engine dispatches only an explicit `automatic`, the builder shows the task as manual, and the task may carry the skip gate and required subtasks.
61
+ */
62
+ trigger_mode?: "manual" | "automatic";
63
+ }
64
+ /**
65
+ * AI extraction + prefill configuration for the attached journey (Flows v2 only)
66
+ */
67
+ export interface AiPrefillConfig {
68
+ enabled?: boolean;
69
+ source?: {
70
+ type?: "flow_context";
71
+ input_entity?: "thread" | "first_email" | "last_email";
72
+ };
73
+ extraction_fields?: AiPrefillExtractionField[];
74
+ mappings?: AiPrefillMapping[];
75
+ min_confidence?: number;
76
+ /**
77
+ * Free-text, cross-field context for the extractor (e.g. "amounts are always in euros")
78
+ */
79
+ instructions?: string;
80
+ }
81
+ export interface AiPrefillExtractionField {
82
+ key: string;
83
+ type: "string" | "number" | "boolean" | "date" | "enum";
84
+ description?: string;
85
+ /**
86
+ * Set when the author replaced the derived description with their own; the builder preserves flagged descriptions across re-derivations
87
+ */
88
+ description_overridden?: boolean;
89
+ enum?: string[];
90
+ }
91
+ export interface AiPrefillMapping {
92
+ source: string;
93
+ block_id: string;
94
+ block_type: "text-input" | "number-input" | "personal-information" | "meter-reading";
95
+ block_field?: string;
51
96
  }
52
97
  /**
53
98
  * Configuration for automation execution to run
@@ -80,18 +125,36 @@ declare namespace Components {
80
125
  */
81
126
  duplicated_flow_id?: string;
82
127
  input_context?: /**
83
- * Optional. Source of the entity fed into this automation task. If omitted, the workflow's primary entity is used.
128
+ * Optional. Source of the entity fed into this automation task. If omitted, the entity of the trigger that started the run is used.
84
129
  *
85
130
  */
86
131
  AutomationInputContext;
132
+ output_context?: /**
133
+ * Optional. What happens to the entity produced by this automation task (the last successful entity-producing action of its automation).
134
+ *
135
+ */
136
+ AutomationOutputContext;
137
+ /**
138
+ * The closing reasons a person may choose from when running this task, making a `cancel-flow-execution` automation semi-automated: the step is configured here, the reason is picked at execution time. Every id must also appear in the flow template's `closing_reasons` — the step narrows the flow's vocabulary rather than introducing its own, which is what keeps the chosen reason a member of the execution's `configured_reasons` and what lets blueprints export the reasons a step depends on. Only a task whose `trigger_mode` is `manual` or absent can carry it; the template healer clears it from an `automatic` task, which has no assignee moment to choose in. Empty or absent means the automation runs with the reasons fixed in its own action config.
139
+ */
140
+ eligible_closing_reason_ids?: string[];
141
+ email_review?: /* Whether the person running a semi-automated send-email step may adjust the email before it goes out, and what they may adjust. Meaningful only on a task a person triggers — the engine's own dispatch has nobody to review — so the template healer clears it from an `automatic` task. With `enabled` false the email is sent exactly as configured and the person only triggers it. */ EmailReviewConfig;
142
+ /**
143
+ * Whether the person running a semi-automated cancel step may add a free-text note alongside the reason they choose. Only meaningful with `eligible_closing_reason_ids`, since the note is written in the same prompt; the template healer clears it from a step that asks nothing.
144
+ */
145
+ allow_execution_note?: boolean;
87
146
  }
88
147
  /**
89
- * Optional. Source of the entity fed into this automation task. If omitted, the workflow's primary entity is used.
148
+ * What the flow does when this automation ends in a failed state. `stop` waits on the failed task until it is retried or skipped. `continue` proceeds to the next task. An absent value means `stop`.
149
+ */
150
+ export type AutomationFailurePolicy = "stop" | "continue";
151
+ /**
152
+ * Optional. Source of the entity fed into this automation task. If omitted, the entity of the trigger that started the run is used.
90
153
  *
91
154
  */
92
155
  export interface AutomationInputContext {
93
156
  /**
94
- * `trigger` = workflow's primary (trigger) entity. `task` = entity produced by an upstream task in the graph.
157
+ * `trigger` = the entity of the trigger that started the run, or of the specific configured trigger named by `trigger_id`. `task` = entity produced by an upstream task in the graph.
95
158
  *
96
159
  */
97
160
  source: "trigger" | "task";
@@ -99,6 +162,27 @@ declare namespace Components {
99
162
  * Required when source is `task`. The id of the upstream task whose output entity should feed this task.
100
163
  */
101
164
  task_id?: string;
165
+ /**
166
+ * Optional when source is `trigger`. Pins the input to one specific configured trigger (primary or additional) by its id. When absent, the trigger that started the run supplies the entity.
167
+ *
168
+ */
169
+ trigger_id?: string;
170
+ }
171
+ /**
172
+ * Optional. What happens to the entity produced by this automation task (the last successful entity-producing action of its automation).
173
+ *
174
+ */
175
+ export interface AutomationOutputContext {
176
+ /**
177
+ * When true, the entity this task's automation produces becomes the run's primary context ("main context") when the task completes. Downstream tasks and decisions configured with the default input context then act on that entity. When the task is reverted or reset, the previous primary context is restored.
178
+ *
179
+ */
180
+ set_as_primary?: boolean;
181
+ /**
182
+ * When true, the entity this task's automation produces is added to the run's contexts without becoming the main one. `set_as_primary` implies this: an entity cannot be the primary context without being a context. Contexts are unique by entity id, so a task that re-produces an entity already on the run adds nothing.
183
+ *
184
+ */
185
+ attach_to_contexts?: boolean;
102
186
  }
103
187
  export interface AutomationTask {
104
188
  id: string;
@@ -115,6 +199,14 @@ declare namespace Components {
115
199
  * requirements that need to be fulfilled in order to enable the task while flow instances are running
116
200
  */
117
201
  requirements?: /* describe the requirement for a task to be enabled */ EnableRequirement[];
202
+ /**
203
+ * When true, the task is required and users cannot skip it while the flow is running. Unrelated to `requirements`, which gate when a task becomes enabled. System-driven skips are unaffected — tasks on a not-taken decision branch, and automation tasks whose automation execution itself reports a skipped verdict (e.g. unmet trigger conditions). Only a manual task, or an automation or AI task whose `trigger_mode` is `manual` or absent, can carry it: on a decision or an automatic kind it is normalised to false on create, update and load.
204
+ */
205
+ required?: boolean;
206
+ /**
207
+ * Checklist items from the task's party descriptions, derived by the server from the checklist markup (`ul[__lexicallisttype="check"] > li[data-subtask-id]`, nearest list ancestor) on every create, update and load — a client-supplied array is replaced. Parties are read in the order description, ecp, installer, partner and the first occurrence of an id wins; an id occurring twice in one task is rejected. An item is required only when it is marked `data-subtask-required="true"` in the markup, the task kind has a person action (a manual task, a decision with `trigger_mode: manual`, or an automation or AI task whose `trigger_mode` is `manual` or absent) and it lives in the co-worker or partner description. Required items gate task completion while the flow is running.
208
+ */
209
+ subtasks?: /* One checklist item of a task, derived from the checklist markup in the party descriptions. Identity is the stable data-subtask-id the editor mints into the markup. */ Subtask[];
118
210
  assigned_to?: (string | /* Represents a variable assignment with its expression and optional resolved value. Used for dynamic user assignments that get resolved during workflow execution. */ VariableAssignment)[];
119
211
  ecp?: /* Details regarding ECP for the workflow step */ ECPDetails;
120
212
  installer?: /* Details regarding ECP for the workflow step */ ECPDetails;
@@ -126,6 +218,7 @@ declare namespace Components {
126
218
  phase_id?: string;
127
219
  task_type: TaskType;
128
220
  automation_config: /* Configuration for automation execution to run */ AutomationConfig;
221
+ on_failure?: /* What the flow does when this automation ends in a failed state. `stop` waits on the failed task until it is retried or skipped. `continue` proceeds to the next task. An absent value means `stop`. */ AutomationFailurePolicy;
129
222
  trigger_mode?: TriggerMode;
130
223
  schedule?: ActionSchedule;
131
224
  /**
@@ -235,6 +328,19 @@ declare namespace Components {
235
328
  * Optional detailed description of the workflow's purpose and behavior.
236
329
  */
237
330
  description?: string;
331
+ /**
332
+ * Portal-facing overrides of the flow name. Portal surfaces (the End Customer and Installer portals, and the builder's portal views) show the matching override instead of `name`; an absent key falls back to `name`. Has no effect on execution behaviour.
333
+ */
334
+ portal_titles?: {
335
+ /**
336
+ * Flow title shown to end customers.
337
+ */
338
+ ecp?: string;
339
+ /**
340
+ * Flow title shown to installers.
341
+ */
342
+ installer?: string;
343
+ };
238
344
  trigger?: /**
239
345
  * example:
240
346
  * {
@@ -282,7 +388,15 @@ declare namespace Components {
282
388
  */
283
389
  available_in_ecp?: boolean;
284
390
  /**
285
- * Additional trigger configurations that can also start this flow. Useful for flows that should be startable via multiple methods (e.g., both automation AND manual).
391
+ * Additional trigger configurations that can also start this flow.
392
+ * Useful for flows that should be startable via multiple methods
393
+ * (e.g., both automation AND manual). Each additional trigger may
394
+ * target its own entity and may carry its own entry edge (an edge
395
+ * whose `from_id` is the trigger's `id`); without an entry edge of
396
+ * its own it starts the flow at the primary entry. Triggers must be
397
+ * complementary — no two triggers on a flow may cover the same
398
+ * entity and event.
399
+ *
286
400
  */
287
401
  additional_triggers?: /**
288
402
  * example:
@@ -293,6 +407,10 @@ declare namespace Components {
293
407
  */
294
408
  Trigger[];
295
409
  phases?: Phase[];
410
+ /**
411
+ * Customer-facing progress segments layered on top of the flow graph. Stages are strictly ordered boundaries: the first is anchored at the trigger, every later one is an edge cut (or a legacy entry-node anchor whose in-edges form the cut). The array order is the boundary order and must match the graph. Per-node stage membership is always computed from the graph, never stored, and a run may end in any stage.
412
+ */
413
+ stages?: /* A customer-facing progress segment layered on top of the flow graph. Unlike phases (internal task grouping), stages exist to communicate progress to outside users (e.g. end customers) with a title and description. Stages form a strict total order; the array order is the boundary order and must match the graph. The first stage's entry node is always the trigger node. */ Stage[];
296
414
  tasks: Task[];
297
415
  edges: Edge[];
298
416
  closing_reasons?: /* One Closing reason for a workflow */ ClosingReason[];
@@ -328,10 +446,21 @@ declare namespace Components {
328
446
  * When true, this is a linear flow: task enablement is computed at runtime from the graph — a task is enabled only when all of its direct predecessor tasks in its branch are done. This fully overrides any explicit per-task requirements.
329
447
  */
330
448
  linear?: boolean;
449
+ context_settings?: /**
450
+ * Where a flow runs, and where people see it.
451
+ * A run is ALWAYS visible on the entities it runs on — the entity its trigger supplied and every context it picks up. That is not configurable: it is what running there means, and hiding a run from its own entity is what `visibility: background` is for.
452
+ * `displays` lists ADDITIONAL entity kinds, reached by relation. It is written once and holds for every trigger: which entry point started a run says how it began, not who the process concerns. A flow that finance must see on the Account must be seen there whether it started from a web form or an inbound email.
453
+ *
454
+ */
455
+ FlowContextSettings;
331
456
  /**
332
457
  * Non-blocking warnings for configuration limits the flow exceeds. Returned on read (get-flow) and on create/update responses. Size/count limits are soft: a flow exceeding them is still accepted and stored, and the violations are reported here so the UI can surface an informational banner. The flow is still fully editable and usable.
333
458
  */
334
459
  limit_warnings?: /* A configuration limit that the flow currently exceeds. Returned by the get-flow endpoint and by create/update responses so the UI can show a non-blocking banner. Size/count limit violations never cause a 400 — only structural errors do. The flow remains fully usable; users are encouraged to bring values within the limits. */ FlowLimitWarning[];
460
+ /**
461
+ * Persisted preference for how the flow's task automations relate to the flow's `enabled` state. When `true`, task automations always mirror the flow: their enabled state is re-synced on every update and new task automations are created with the flow's current enabled state. When `false`, task automations are managed independently: updates never change their enabled state and new task automations are always created enabled, so a flow that is built or edited while disabled does not accumulate automations that stay off after the flow is re-enabled. When unset, legacy behavior applies: new task automations inherit the flow's enabled state and updates leave existing ones untouched. Safety: on updates that do NOT change `enabled`, the in-sync mode never re-enables automations that were disabled by the system (e.g. infinite-loop protection) — only a deliberate `enabled` flip on the flow re-arms those.
462
+ */
463
+ keep_task_automations_in_sync?: boolean;
335
464
  }
336
465
  export interface DecisionTask {
337
466
  id: string;
@@ -348,6 +477,14 @@ declare namespace Components {
348
477
  * requirements that need to be fulfilled in order to enable the task while flow instances are running
349
478
  */
350
479
  requirements?: /* describe the requirement for a task to be enabled */ EnableRequirement[];
480
+ /**
481
+ * When true, the task is required and users cannot skip it while the flow is running. Unrelated to `requirements`, which gate when a task becomes enabled. System-driven skips are unaffected — tasks on a not-taken decision branch, and automation tasks whose automation execution itself reports a skipped verdict (e.g. unmet trigger conditions). Only a manual task, or an automation or AI task whose `trigger_mode` is `manual` or absent, can carry it: on a decision or an automatic kind it is normalised to false on create, update and load.
482
+ */
483
+ required?: boolean;
484
+ /**
485
+ * Checklist items from the task's party descriptions, derived by the server from the checklist markup (`ul[__lexicallisttype="check"] > li[data-subtask-id]`, nearest list ancestor) on every create, update and load — a client-supplied array is replaced. Parties are read in the order description, ecp, installer, partner and the first occurrence of an id wins; an id occurring twice in one task is rejected. An item is required only when it is marked `data-subtask-required="true"` in the markup, the task kind has a person action (a manual task, a decision with `trigger_mode: manual`, or an automation or AI task whose `trigger_mode` is `manual` or absent) and it lives in the co-worker or partner description. Required items gate task completion while the flow is running.
486
+ */
487
+ subtasks?: /* One checklist item of a task, derived from the checklist markup in the party descriptions. Identity is the stable data-subtask-id the editor mints into the markup. */ Subtask[];
351
488
  assigned_to?: (string | /* Represents a variable assignment with its expression and optional resolved value. Used for dynamic user assignments that get resolved during workflow execution. */ VariableAssignment)[];
352
489
  ecp?: /* Details regarding ECP for the workflow step */ ECPDetails;
353
490
  installer?: /* Details regarding ECP for the workflow step */ ECPDetails;
@@ -361,7 +498,7 @@ declare namespace Components {
361
498
  trigger_mode: TriggerMode;
362
499
  conditions: Condition[];
363
500
  /**
364
- * When true, all branches with met conditions execute in parallel. When false, only the first branch with a met condition is executed. Defaults to true for backwards compatibility.
501
+ * When true, all branches with met conditions execute in parallel. When false, only the first branch with a met condition is executed. The default depends on the trigger mode: automatic decisions treat an absent field as true (backwards compatibility), while manual decisions require an explicit true before multiple branches can be selected at execution time (absent = single-select).
365
502
  */
366
503
  allow_parallel_execution?: boolean;
367
504
  schedule?: DelayedSchedule | RelativeSchedule;
@@ -434,6 +571,13 @@ declare namespace Components {
434
571
  }
435
572
  export interface Edge {
436
573
  id: string;
574
+ /**
575
+ * Source node of the edge: a task id, a phase id, the literal `trigger`
576
+ * (the primary trigger's entry edge), or an additional trigger's `id`
577
+ * (that trigger's own entry edge — allowing the flow to start at a
578
+ * different node depending on which trigger fired).
579
+ *
580
+ */
437
581
  from_id: string;
438
582
  to_id?: string | null;
439
583
  condition_id?: string;
@@ -442,6 +586,20 @@ declare namespace Components {
442
586
  */
443
587
  none_met?: boolean;
444
588
  }
589
+ /**
590
+ * Whether the person running a semi-automated send-email step may adjust the email before it goes out, and what they may adjust. Meaningful only on a task a person triggers — the engine's own dispatch has nobody to review — so the template healer clears it from an `automatic` task. With `enabled` false the email is sent exactly as configured and the person only triggers it.
591
+ */
592
+ export interface EmailReviewConfig {
593
+ enabled?: boolean;
594
+ /**
595
+ * The assignee may attach documents from the task's entity at execution, in addition to whatever the configured rules match.
596
+ */
597
+ allow_document_selection?: boolean;
598
+ /**
599
+ * The assignee may rewrite the rendered subject and body. They edit the rendered text, not the template, so the template is unchanged and other flows using it are unaffected.
600
+ */
601
+ allow_subject_and_body_edit?: boolean;
602
+ }
445
603
  /**
446
604
  * describe the requirement for a task to be enabled
447
605
  */
@@ -536,7 +694,12 @@ declare namespace Components {
536
694
  */
537
695
  id?: string;
538
696
  origin?: "trigger" | "action";
539
- origin_type?: "entity" | "workflow" | "journey_block";
697
+ /**
698
+ * `trigger_source` (with origin `trigger`) marks a "started by" statement: the run's fired trigger is compared against the configured trigger ids in `values` — no entity attribute is involved.
699
+ * `main_context` (with origin `trigger`, no `id`) marks a statement evaluated against the run's PRIMARY context: the fired trigger's entity, re-bound by any completed task that promotes its output to main context (`output_context.set_as_primary`). `schema` carries the subject's schema for attribute selection only — resolution is by the primary flag, never by schema.
700
+ *
701
+ */
702
+ origin_type?: "entity" | "workflow" | "journey_block" | "trigger_source" | "main_context";
540
703
  schema?: string;
541
704
  attribute?: string;
542
705
  attribute_type?: "string" | "text" | "number" | "boolean" | "date" | "datetime" | "tags" | "country" | "email" | "phone" | "product" | "price" | "status" | "relation" | "multiselect" | "select" | "radio" | "relation_user" | "purpose" | "label" | "message_email_address";
@@ -588,6 +751,69 @@ declare namespace Components {
588
751
  unit?: "days" | "months" | "years";
589
752
  };
590
753
  }
754
+ /**
755
+ * Where a flow runs, and where people see it.
756
+ * A run is ALWAYS visible on the entities it runs on — the entity its trigger supplied and every context it picks up. That is not configurable: it is what running there means, and hiding a run from its own entity is what `visibility: background` is for.
757
+ * `displays` lists ADDITIONAL entity kinds, reached by relation. It is written once and holds for every trigger: which entry point started a run says how it began, not who the process concerns. A flow that finance must see on the Account must be seen there whether it started from a web form or an inbound email.
758
+ *
759
+ */
760
+ export interface FlowContextSettings {
761
+ /**
762
+ * `entity_views` — the flow appears on entity pages, table views and the portal, as decided by `displays`.
763
+ * `background` — the flow is hidden from every entity view. It runs and records exactly the same way; only the surfaces are suppressed.
764
+ *
765
+ */
766
+ visibility?: "entity_views" | "background";
767
+ main_context?: /**
768
+ * Which of a flow's contexts owns the run: the entity conditions, automations and entity sync resolve against by default.
769
+ * ABSENT means the historical behaviour — the primary trigger's entity. That default exists because it describes every flow built so far, not because the primary trigger is special: a flow with several complementary triggers has no natural primary, which is exactly when stating it explicitly earns its place.
770
+ * This decides the STARTING main context only. A task with `output_context.set_as_primary` still moves it mid-run; the setting seeds the run and the graph moves it from there.
771
+ *
772
+ */
773
+ MainContextSetting;
774
+ /**
775
+ * Additional entity kinds this flow is visible on, beyond the entities it runs on. Empty or absent means it is seen only where it runs.
776
+ * ORDERED. An entry may anchor (`from`) only on the main context or on an EARLIER entry. That ordering is what makes a cycle (contact anchored on account anchored on contact) unrepresentable rather than something to detect at runtime.
777
+ *
778
+ */
779
+ displays?: /**
780
+ * One additional entity kind the flow should be visible on, found by relation from the main context or from an earlier entry.
781
+ * An entity reached this way has no context of its own: it shows the main context's run, and acting on it acts on the main context. Nothing is copied and no second run starts.
782
+ * There is no `enabled` flag and no entry for an entity the flow already runs on. An entry exists because someone wants the flow seen there; remove it to stop. Whether an entity is a context at all is decided by the trigger, by a task's `output_context`, or by `attach_to_contexts` below — never by a display setting.
783
+ *
784
+ */
785
+ FlowDisplayRule[];
786
+ }
787
+ /**
788
+ * One additional entity kind the flow should be visible on, found by relation from the main context or from an earlier entry.
789
+ * An entity reached this way has no context of its own: it shows the main context's run, and acting on it acts on the main context. Nothing is copied and no second run starts.
790
+ * There is no `enabled` flag and no entry for an entity the flow already runs on. An entry exists because someone wants the flow seen there; remove it to stop. Whether an entity is a context at all is decided by the trigger, by a task's `output_context`, or by `attach_to_contexts` below — never by a display setting.
791
+ *
792
+ */
793
+ export interface FlowDisplayRule {
794
+ id: string;
795
+ /**
796
+ * The schema of the entity this rule is about.
797
+ */
798
+ entity_schema: string;
799
+ from?: /**
800
+ * Where an entry starts looking. Absent means `main_context`.
801
+ * A ROLE, not a schema: an entry anchored on `main_context` follows the primary when a task promotes another entity, where naming a schema would freeze it on the old one.
802
+ *
803
+ */
804
+ FlowRuleAnchor;
805
+ /**
806
+ * Relation `_tags` to match (`family:label` form supported). Absent or empty matches every relation of `entity_schema`.
807
+ *
808
+ */
809
+ relation_labels?: string[];
810
+ /**
811
+ * Governs CONTEXT. When true the matched entity is added to the run's contexts, so later rules can anchor on it and conditions, entity sync and task automations can address it. Resolved by the ENGINE — at start and whenever the contexts change — never as a side effect of rendering, which would make a run's context set depend on who opened which page.
812
+ * A context must resolve to one entity: when several match, none is attached. Display is unaffected and still shows all of them.
813
+ *
814
+ */
815
+ attach_to_contexts?: boolean;
816
+ }
591
817
  /**
592
818
  * A configuration limit that the flow currently exceeds. Returned by the get-flow endpoint and by create/update responses so the UI can show a non-blocking banner. Size/count limit violations never cause a 400 — only structural errors do. The flow remains fully usable; users are encouraged to bring values within the limits.
593
819
  */
@@ -623,6 +849,21 @@ declare namespace Components {
623
849
  */
624
850
  path: any[];
625
851
  }
852
+ /**
853
+ * Where an entry starts looking. Absent means `main_context`.
854
+ * A ROLE, not a schema: an entry anchored on `main_context` follows the primary when a task promotes another entity, where naming a schema would freeze it on the old one.
855
+ *
856
+ */
857
+ export type FlowRuleAnchor = /**
858
+ * Where an entry starts looking. Absent means `main_context`.
859
+ * A ROLE, not a schema: an entry anchored on `main_context` follows the primary when a task promotes another entity, where naming a schema would freeze it on the old one.
860
+ *
861
+ */
862
+ /* The run's primary context, whatever it currently is. */ MainContextAnchor | /**
863
+ * An earlier entry in `displays`, by its id: this entry searches from whatever that one matched. Chaining ticket -> contact -> account this way keeps both hops DISPLAY-only; making the contact a real context first is a separate decision (`attach_to_contexts`), not a prerequisite for reaching the account.
864
+ *
865
+ */
866
+ RuleAnchor;
626
867
  /**
627
868
  * Base schema for V2 flow templates. A flow template defines the structure of a workflow
628
869
  * including phases, tasks, edges, triggers, and other configuration. Flow templates serve
@@ -646,6 +887,19 @@ declare namespace Components {
646
887
  * Optional detailed description of the workflow's purpose and behavior.
647
888
  */
648
889
  description?: string;
890
+ /**
891
+ * Portal-facing overrides of the flow name. Portal surfaces (the End Customer and Installer portals, and the builder's portal views) show the matching override instead of `name`; an absent key falls back to `name`. Has no effect on execution behaviour.
892
+ */
893
+ portal_titles?: {
894
+ /**
895
+ * Flow title shown to end customers.
896
+ */
897
+ ecp?: string;
898
+ /**
899
+ * Flow title shown to installers.
900
+ */
901
+ installer?: string;
902
+ };
649
903
  trigger?: /**
650
904
  * example:
651
905
  * {
@@ -693,7 +947,15 @@ declare namespace Components {
693
947
  */
694
948
  available_in_ecp?: boolean;
695
949
  /**
696
- * Additional trigger configurations that can also start this flow. Useful for flows that should be startable via multiple methods (e.g., both automation AND manual).
950
+ * Additional trigger configurations that can also start this flow.
951
+ * Useful for flows that should be startable via multiple methods
952
+ * (e.g., both automation AND manual). Each additional trigger may
953
+ * target its own entity and may carry its own entry edge (an edge
954
+ * whose `from_id` is the trigger's `id`); without an entry edge of
955
+ * its own it starts the flow at the primary entry. Triggers must be
956
+ * complementary — no two triggers on a flow may cover the same
957
+ * entity and event.
958
+ *
697
959
  */
698
960
  additional_triggers?: /**
699
961
  * example:
@@ -704,6 +966,10 @@ declare namespace Components {
704
966
  */
705
967
  Trigger[];
706
968
  phases?: Phase[];
969
+ /**
970
+ * Customer-facing progress segments layered on top of the flow graph. Stages are strictly ordered boundaries: the first is anchored at the trigger, every later one is an edge cut (or a legacy entry-node anchor whose in-edges form the cut). The array order is the boundary order and must match the graph. Per-node stage membership is always computed from the graph, never stored, and a run may end in any stage.
971
+ */
972
+ stages?: /* A customer-facing progress segment layered on top of the flow graph. Unlike phases (internal task grouping), stages exist to communicate progress to outside users (e.g. end customers) with a title and description. Stages form a strict total order; the array order is the boundary order and must match the graph. The first stage's entry node is always the trigger node. */ Stage[];
707
973
  tasks: Task[];
708
974
  edges: Edge[];
709
975
  closing_reasons?: /* One Closing reason for a workflow */ ClosingReason[];
@@ -739,10 +1005,21 @@ declare namespace Components {
739
1005
  * When true, this is a linear flow: task enablement is computed at runtime from the graph — a task is enabled only when all of its direct predecessor tasks in its branch are done. This fully overrides any explicit per-task requirements.
740
1006
  */
741
1007
  linear?: boolean;
1008
+ context_settings?: /**
1009
+ * Where a flow runs, and where people see it.
1010
+ * A run is ALWAYS visible on the entities it runs on — the entity its trigger supplied and every context it picks up. That is not configurable: it is what running there means, and hiding a run from its own entity is what `visibility: background` is for.
1011
+ * `displays` lists ADDITIONAL entity kinds, reached by relation. It is written once and holds for every trigger: which entry point started a run says how it began, not who the process concerns. A flow that finance must see on the Account must be seen there whether it started from a web form or an inbound email.
1012
+ *
1013
+ */
1014
+ FlowContextSettings;
742
1015
  /**
743
1016
  * Non-blocking warnings for configuration limits the flow exceeds. Returned on read (get-flow) and on create/update responses. Size/count limits are soft: a flow exceeding them is still accepted and stored, and the violations are reported here so the UI can surface an informational banner. The flow is still fully editable and usable.
744
1017
  */
745
1018
  limit_warnings?: /* A configuration limit that the flow currently exceeds. Returned by the get-flow endpoint and by create/update responses so the UI can show a non-blocking banner. Size/count limit violations never cause a 400 — only structural errors do. The flow remains fully usable; users are encouraged to bring values within the limits. */ FlowLimitWarning[];
1019
+ /**
1020
+ * Persisted preference for how the flow's task automations relate to the flow's `enabled` state. When `true`, task automations always mirror the flow: their enabled state is re-synced on every update and new task automations are created with the flow's current enabled state. When `false`, task automations are managed independently: updates never change their enabled state and new task automations are always created enabled, so a flow that is built or edited while disabled does not accumulate automations that stay off after the flow is re-enabled. When unset, legacy behavior applies: new task automations inherit the flow's enabled state and updates leave existing ones untouched. Safety: on updates that do NOT change `enabled`, the in-sync mode never re-enables automations that were disabled by the system (e.g. infinite-loop protection) — only a deliberate `enabled` flip on the flow re-arms those.
1021
+ */
1022
+ keep_task_automations_in_sync?: boolean;
746
1023
  }
747
1024
  /**
748
1025
  * Base schema for V2 flow templates. A flow template defines the structure of a workflow
@@ -767,6 +1044,19 @@ declare namespace Components {
767
1044
  * Optional detailed description of the workflow's purpose and behavior.
768
1045
  */
769
1046
  description?: string;
1047
+ /**
1048
+ * Portal-facing overrides of the flow name. Portal surfaces (the End Customer and Installer portals, and the builder's portal views) show the matching override instead of `name`; an absent key falls back to `name`. Has no effect on execution behaviour.
1049
+ */
1050
+ portal_titles?: {
1051
+ /**
1052
+ * Flow title shown to end customers.
1053
+ */
1054
+ ecp?: string;
1055
+ /**
1056
+ * Flow title shown to installers.
1057
+ */
1058
+ installer?: string;
1059
+ };
770
1060
  trigger?: /**
771
1061
  * example:
772
1062
  * {
@@ -814,7 +1104,15 @@ declare namespace Components {
814
1104
  */
815
1105
  available_in_ecp?: boolean;
816
1106
  /**
817
- * Additional trigger configurations that can also start this flow. Useful for flows that should be startable via multiple methods (e.g., both automation AND manual).
1107
+ * Additional trigger configurations that can also start this flow.
1108
+ * Useful for flows that should be startable via multiple methods
1109
+ * (e.g., both automation AND manual). Each additional trigger may
1110
+ * target its own entity and may carry its own entry edge (an edge
1111
+ * whose `from_id` is the trigger's `id`); without an entry edge of
1112
+ * its own it starts the flow at the primary entry. Triggers must be
1113
+ * complementary — no two triggers on a flow may cover the same
1114
+ * entity and event.
1115
+ *
818
1116
  */
819
1117
  additional_triggers?: /**
820
1118
  * example:
@@ -825,6 +1123,10 @@ declare namespace Components {
825
1123
  */
826
1124
  Trigger[];
827
1125
  phases?: Phase[];
1126
+ /**
1127
+ * Customer-facing progress segments layered on top of the flow graph. Stages are strictly ordered boundaries: the first is anchored at the trigger, every later one is an edge cut (or a legacy entry-node anchor whose in-edges form the cut). The array order is the boundary order and must match the graph. Per-node stage membership is always computed from the graph, never stored, and a run may end in any stage.
1128
+ */
1129
+ stages?: /* A customer-facing progress segment layered on top of the flow graph. Unlike phases (internal task grouping), stages exist to communicate progress to outside users (e.g. end customers) with a title and description. Stages form a strict total order; the array order is the boundary order and must match the graph. The first stage's entry node is always the trigger node. */ Stage[];
828
1130
  tasks: Task[];
829
1131
  edges: Edge[];
830
1132
  closing_reasons?: /* One Closing reason for a workflow */ ClosingReason[];
@@ -860,10 +1162,21 @@ declare namespace Components {
860
1162
  * When true, this is a linear flow: task enablement is computed at runtime from the graph — a task is enabled only when all of its direct predecessor tasks in its branch are done. This fully overrides any explicit per-task requirements.
861
1163
  */
862
1164
  linear?: boolean;
1165
+ context_settings?: /**
1166
+ * Where a flow runs, and where people see it.
1167
+ * A run is ALWAYS visible on the entities it runs on — the entity its trigger supplied and every context it picks up. That is not configurable: it is what running there means, and hiding a run from its own entity is what `visibility: background` is for.
1168
+ * `displays` lists ADDITIONAL entity kinds, reached by relation. It is written once and holds for every trigger: which entry point started a run says how it began, not who the process concerns. A flow that finance must see on the Account must be seen there whether it started from a web form or an inbound email.
1169
+ *
1170
+ */
1171
+ FlowContextSettings;
863
1172
  /**
864
1173
  * Non-blocking warnings for configuration limits the flow exceeds. Returned on read (get-flow) and on create/update responses. Size/count limits are soft: a flow exceeding them is still accepted and stored, and the violations are reported here so the UI can surface an informational banner. The flow is still fully editable and usable.
865
1174
  */
866
1175
  limit_warnings?: /* A configuration limit that the flow currently exceeds. Returned by the get-flow endpoint and by create/update responses so the UI can show a non-blocking banner. Size/count limit violations never cause a 400 — only structural errors do. The flow remains fully usable; users are encouraged to bring values within the limits. */ FlowLimitWarning[];
1176
+ /**
1177
+ * Persisted preference for how the flow's task automations relate to the flow's `enabled` state. When `true`, task automations always mirror the flow: their enabled state is re-synced on every update and new task automations are created with the flow's current enabled state. When `false`, task automations are managed independently: updates never change their enabled state and new task automations are always created enabled, so a flow that is built or edited while disabled does not accumulate automations that stay off after the flow is re-enabled. When unset, legacy behavior applies: new task automations inherit the flow's enabled state and updates leave existing ones untouched. Safety: on updates that do NOT change `enabled`, the in-sync mode never re-enables automations that were disabled by the system (e.g. infinite-loop protection) — only a deliberate `enabled` flip on the flow re-arms those.
1178
+ */
1179
+ keep_task_automations_in_sync?: boolean;
867
1180
  }
868
1181
  /**
869
1182
  * Short unique id (length 8) to identify the Flow Template.
@@ -892,6 +1205,91 @@ declare namespace Components {
892
1205
  */
893
1206
  entity_schema?: string;
894
1207
  }
1208
+ export interface JourneyContextParameter {
1209
+ /**
1210
+ * The journey context parameter key (paramKey in the journey's contextSchema)
1211
+ */
1212
+ key: string;
1213
+ /**
1214
+ * The value to pass for the parameter when launching the journey
1215
+ */
1216
+ value: string;
1217
+ }
1218
+ /**
1219
+ * One place a flow template task presets one of the requested context parameters.
1220
+ */
1221
+ export interface JourneyContextUsage {
1222
+ kind: "workflow-task";
1223
+ resource: {
1224
+ type: "workflow_template";
1225
+ /**
1226
+ * Flow template id.
1227
+ */
1228
+ id: string;
1229
+ /**
1230
+ * Flow template name, when the template has one.
1231
+ */
1232
+ name?: string;
1233
+ };
1234
+ /**
1235
+ * Present only when the matching task carries an id and/or a name.
1236
+ */
1237
+ location?: {
1238
+ task_id?: string;
1239
+ task_name?: string;
1240
+ };
1241
+ matched_as: {
1242
+ dialect: "name";
1243
+ /**
1244
+ * The bare parameter key, e.g. `origin` — never a `journey_context.origin`-style prefixed token. Unlike every sibling adapter, this service stores the reference structurally in a typed field (`tasks[].journey.context_parameters[].key`), so the prefixed path string never appears in the stored record; `dialect: name` already tells the caller how to interpret `token`.
1245
+ */
1246
+ token: string;
1247
+ /**
1248
+ * Debugging path into the flow template where the match was found, e.g. `tasks[0].journey.context_parameters[1].key`. Not stable across edits to the template.
1249
+ */
1250
+ at: string;
1251
+ };
1252
+ /**
1253
+ * Omitted when the underlying flow template has no id: a link built from an empty id could not resolve, so none is included. The usage row itself is still reported.
1254
+ */
1255
+ link_hint?: {
1256
+ route: "workflows-hub-flow";
1257
+ params: {
1258
+ template_id: string;
1259
+ };
1260
+ };
1261
+ }
1262
+ /**
1263
+ * Request payload for getJourneyContextUsages.
1264
+ */
1265
+ export interface JourneyContextUsagesReq {
1266
+ /**
1267
+ * Journey whose context parameters are being checked for usage.
1268
+ */
1269
+ journey_id: string;
1270
+ /**
1271
+ * Context parameter keys to look for, as plain strings.
1272
+ */
1273
+ param_keys: string[];
1274
+ /**
1275
+ * Accepted and ignored. This service stores context references by name only; the field keeps one request shape across every adapter in this feature.
1276
+ */
1277
+ param_ids?: string[];
1278
+ }
1279
+ /**
1280
+ * Response payload for getJourneyContextUsages.
1281
+ */
1282
+ export interface JourneyContextUsagesResp {
1283
+ usages: /* One place a flow template task presets one of the requested context parameters. */ JourneyContextUsage[];
1284
+ /**
1285
+ * `partial` means the usages list hit its cap and the scan stopped there, before every scannable flow template in the org was examined. `ok` means the scan reached the end of the scannable population and returned every match found there — it does NOT mean every flow template in the org was examined: the underlying query only returns `version = v3` records, so legacy v1/v2 templates never enter the scan, and any record that fails to normalize is silently skipped and logged rather than failing the whole lookup.
1286
+ */
1287
+ status: "ok" | "partial";
1288
+ /**
1289
+ * Count of flow templates examined. This is every scannable flow template in the org, not only templates bound to this journey: the underlying query has no server-side journey filter, so it counts the org's whole scannable flow-template population, up to wherever the scan stopped if `status` is `partial`. "Scannable" excludes legacy v1/v2 records (the query filters to `version = v3`) and any record that fails to normalize (skipped and logged rather than failing the lookup), so this can be lower than the org's true total flow-template count.
1290
+ */
1291
+ scanned: number;
1292
+ }
895
1293
  export interface JourneySubmissionTrigger {
896
1294
  id?: string;
897
1295
  type: "journey_submission";
@@ -905,6 +1303,31 @@ declare namespace Components {
905
1303
  journey_name?: string;
906
1304
  automation_id?: string;
907
1305
  }
1306
+ /**
1307
+ * The run's primary context, whatever it currently is.
1308
+ */
1309
+ export interface MainContextAnchor {
1310
+ role: "main_context";
1311
+ }
1312
+ /**
1313
+ * Which of a flow's contexts owns the run: the entity conditions, automations and entity sync resolve against by default.
1314
+ * ABSENT means the historical behaviour — the primary trigger's entity. That default exists because it describes every flow built so far, not because the primary trigger is special: a flow with several complementary triggers has no natural primary, which is exactly when stating it explicitly earns its place.
1315
+ * This decides the STARTING main context only. A task with `output_context.set_as_primary` still moves it mid-run; the setting seeds the run and the graph moves it from there.
1316
+ *
1317
+ */
1318
+ export interface MainContextSetting {
1319
+ /**
1320
+ * Entity schema of the main context. It need not be a schema any trigger provides: a run started on another context resolves it from that entity's relations.
1321
+ */
1322
+ schema: string;
1323
+ /**
1324
+ * Optional narrowing for that resolution. A run started on a context of another schema looks through the starting entity's relations for one of `schema`; these `_tags` narrow which relations count, for when schema alone is ambiguous.
1325
+ * Several matches: the FIRST is taken. Unlike an attaching display rule — which attaches nothing when several match, since binding an arbitrary entity as a surface has no justification — a run needs a primary to function at all, so a deterministic pick beats none.
1326
+ * No match: the run starts with the entity it was started on as primary, and records that the configured main context did not resolve. A manual start is never blocked because a relation happens to be missing.
1327
+ *
1328
+ */
1329
+ relation_labels?: string[];
1330
+ }
908
1331
  export interface ManualTask {
909
1332
  id: string;
910
1333
  name: string;
@@ -920,6 +1343,14 @@ declare namespace Components {
920
1343
  * requirements that need to be fulfilled in order to enable the task while flow instances are running
921
1344
  */
922
1345
  requirements?: /* describe the requirement for a task to be enabled */ EnableRequirement[];
1346
+ /**
1347
+ * When true, the task is required and users cannot skip it while the flow is running. Unrelated to `requirements`, which gate when a task becomes enabled. System-driven skips are unaffected — tasks on a not-taken decision branch, and automation tasks whose automation execution itself reports a skipped verdict (e.g. unmet trigger conditions). Only a manual task, or an automation or AI task whose `trigger_mode` is `manual` or absent, can carry it: on a decision or an automatic kind it is normalised to false on create, update and load.
1348
+ */
1349
+ required?: boolean;
1350
+ /**
1351
+ * Checklist items from the task's party descriptions, derived by the server from the checklist markup (`ul[__lexicallisttype="check"] > li[data-subtask-id]`, nearest list ancestor) on every create, update and load — a client-supplied array is replaced. Parties are read in the order description, ecp, installer, partner and the first occurrence of an id wins; an id occurring twice in one task is rejected. An item is required only when it is marked `data-subtask-required="true"` in the markup, the task kind has a person action (a manual task, a decision with `trigger_mode: manual`, or an automation or AI task whose `trigger_mode` is `manual` or absent) and it lives in the co-worker or partner description. Required items gate task completion while the flow is running.
1352
+ */
1353
+ subtasks?: /* One checklist item of a task, derived from the checklist markup in the party descriptions. Identity is the stable data-subtask-id the editor mints into the markup. */ Subtask[];
923
1354
  assigned_to?: (string | /* Represents a variable assignment with its expression and optional resolved value. Used for dynamic user assignments that get resolved during workflow execution. */ VariableAssignment)[];
924
1355
  ecp?: /* Details regarding ECP for the workflow step */ ECPDetails;
925
1356
  installer?: /* Details regarding ECP for the workflow step */ ECPDetails;
@@ -985,6 +1416,17 @@ declare namespace Components {
985
1416
  attribute?: string;
986
1417
  };
987
1418
  }
1419
+ /**
1420
+ * An earlier entry in `displays`, by its id: this entry searches from whatever that one matched. Chaining ticket -> contact -> account this way keeps both hops DISPLAY-only; making the contact a real context first is a separate decision (`attach_to_contexts`), not a prerequisite for reaching the account.
1421
+ *
1422
+ */
1423
+ export interface RuleAnchor {
1424
+ role: "rule";
1425
+ /**
1426
+ * Id of an entry that appears earlier in `displays`.
1427
+ */
1428
+ rule_id: string;
1429
+ }
988
1430
  export interface SearchFlowTemplates {
989
1431
  name?: string;
990
1432
  definition_id?: string;
@@ -992,7 +1434,7 @@ declare namespace Components {
992
1434
  enabled?: boolean;
993
1435
  from?: number;
994
1436
  size?: number;
995
- sort_by?: "created_at" | "updated_at";
1437
+ sort_by?: "created_at" | "updated_at" | "name" | "enabled" | "id";
996
1438
  sort_order?: "asc" | "desc";
997
1439
  }
998
1440
  /**
@@ -1023,6 +1465,61 @@ declare namespace Components {
1023
1465
  */
1024
1466
  taxonomies?: string[];
1025
1467
  }
1468
+ /**
1469
+ * A customer-facing progress segment layered on top of the flow graph. Unlike phases (internal task grouping), stages exist to communicate progress to outside users (e.g. end customers) with a title and description. Stages form a strict total order; the array order is the boundary order and must match the graph. The first stage's entry node is always the trigger node.
1470
+ */
1471
+ export interface Stage {
1472
+ /**
1473
+ * Stable unique identifier for the stage.
1474
+ */
1475
+ id: string;
1476
+ /**
1477
+ * User-facing stage title.
1478
+ */
1479
+ name: string;
1480
+ /**
1481
+ * Customer-facing description of what happens in this stage.
1482
+ */
1483
+ description?: string;
1484
+ /**
1485
+ * Id of the graph node (task, phase, or the trigger sentinel) at which this stage begins; its incoming edges form the stage boundary, so no path may reach the node's successors without passing it. The first stage's entry_node_id is the trigger sentinel. Exactly one of entry_node_id / cut_edge_ids per stage; when both are present, cut_edge_ids wins.
1486
+ */
1487
+ entry_node_id?: string;
1488
+ /**
1489
+ * Edge-cut boundary, for stages that begin inside branching regions: the stage begins where these edges are crossed — one cut edge per branch that continues past the boundary, so that no path crosses it twice and none bypasses it. Branches that end before the boundary need no cut; a run may end in any stage. Cut edges may not be loop edges, end edges, or phase-internal edges. Node membership is derived by counting crossed boundaries, never stored.
1490
+ */
1491
+ cut_edge_ids?: string[];
1492
+ /**
1493
+ * Optional stage accent color, a key from a fixed palette.
1494
+ */
1495
+ color?: string;
1496
+ /**
1497
+ * Portal-facing overrides of the stage name. Portal surfaces show the matching override instead of `name`; an absent key falls back to `name`.
1498
+ */
1499
+ portal_names?: {
1500
+ /**
1501
+ * Stage name shown to end customers.
1502
+ */
1503
+ ecp?: string;
1504
+ /**
1505
+ * Stage name shown to installers.
1506
+ */
1507
+ installer?: string;
1508
+ };
1509
+ /**
1510
+ * Portal-facing overrides of the stage description. Portal surfaces show the matching override instead of `description`; an absent key falls back to `description`.
1511
+ */
1512
+ portal_descriptions?: {
1513
+ /**
1514
+ * Stage description shown to end customers.
1515
+ */
1516
+ ecp?: string;
1517
+ /**
1518
+ * Stage description shown to installers.
1519
+ */
1520
+ installer?: string;
1521
+ };
1522
+ }
1026
1523
  export interface Statement {
1027
1524
  id: string;
1028
1525
  source: EvaluationSource;
@@ -1094,10 +1591,23 @@ declare namespace Components {
1094
1591
  id?: string;
1095
1592
  journeyId?: string;
1096
1593
  name?: string;
1594
+ /**
1595
+ * Portal-facing label that replaces the default "Start now" button shown for this task's linked journey in the End Customer Portal / Installer Portal. Blank or absent means the portal keeps its own translated default.
1596
+ */
1597
+ portal_button_label?: string;
1097
1598
  /**
1098
1599
  * If true, the task be auto completed when the journey is completed. By default it is true.
1099
1600
  */
1100
1601
  complete_task_automatically?: boolean;
1602
+ /**
1603
+ * When true, the task cannot be completed while the flow is running until the linked journey was actually submitted. The execution service verifies the submission server-side via the correlation claims in the submission entity's journey_context. Manual tasks only: on any other task kind, or on a manual task with a delayed or relative schedule, the template is rejected (400); when no journey is linked the flag is dropped on create, update and load.
1604
+ */
1605
+ journey_submission_required?: boolean;
1606
+ /**
1607
+ * Values preset by the flow author for context parameters the journey declares in its contextSchema (String/Number parameters only, not entity-typed ones). Passed as journey context when the journey is launched from the task, overriding the default value of the parameter (e.g. `origin`).
1608
+ */
1609
+ context_parameters?: JourneyContextParameter[];
1610
+ ai_prefill?: /* AI extraction + prefill configuration for the attached journey (Flows v2 only) */ AiPrefillConfig;
1101
1611
  }
1102
1612
  /**
1103
1613
  * describe the requirement for step enablement
@@ -1108,6 +1618,27 @@ declare namespace Components {
1108
1618
  condition: "CLOSED";
1109
1619
  }
1110
1620
  export type StepType = "MANUAL" | "AUTOMATION";
1621
+ /**
1622
+ * One checklist item of a task, derived from the checklist markup in the party descriptions. Identity is the stable data-subtask-id the editor mints into the markup.
1623
+ */
1624
+ export interface Subtask {
1625
+ /**
1626
+ * Stable id, mirrored as data-subtask-id in the description markup
1627
+ */
1628
+ id: string;
1629
+ /**
1630
+ * Plain-text snapshot of the checklist item label
1631
+ */
1632
+ name?: string;
1633
+ /**
1634
+ * Which description field the item lives in
1635
+ */
1636
+ party: "description" | "ecp" | "installer" | "partner";
1637
+ /**
1638
+ * When true, the task cannot be completed while the flow is running until this item is checked
1639
+ */
1640
+ required?: boolean;
1641
+ }
1111
1642
  export type Task = ManualTask | AutomationTask | DecisionTask | AiAgentTask;
1112
1643
  export interface TaskBase {
1113
1644
  id: string;
@@ -1124,6 +1655,14 @@ declare namespace Components {
1124
1655
  * requirements that need to be fulfilled in order to enable the task while flow instances are running
1125
1656
  */
1126
1657
  requirements?: /* describe the requirement for a task to be enabled */ EnableRequirement[];
1658
+ /**
1659
+ * When true, the task is required and users cannot skip it while the flow is running. Unrelated to `requirements`, which gate when a task becomes enabled. System-driven skips are unaffected — tasks on a not-taken decision branch, and automation tasks whose automation execution itself reports a skipped verdict (e.g. unmet trigger conditions). Only a manual task, or an automation or AI task whose `trigger_mode` is `manual` or absent, can carry it: on a decision or an automatic kind it is normalised to false on create, update and load.
1660
+ */
1661
+ required?: boolean;
1662
+ /**
1663
+ * Checklist items from the task's party descriptions, derived by the server from the checklist markup (`ul[__lexicallisttype="check"] > li[data-subtask-id]`, nearest list ancestor) on every create, update and load — a client-supplied array is replaced. Parties are read in the order description, ecp, installer, partner and the first occurrence of an id wins; an id occurring twice in one task is rejected. An item is required only when it is marked `data-subtask-required="true"` in the markup, the task kind has a person action (a manual task, a decision with `trigger_mode: manual`, or an automation or AI task whose `trigger_mode` is `manual` or absent) and it lives in the co-worker or partner description. Required items gate task completion while the flow is running.
1664
+ */
1665
+ subtasks?: /* One checklist item of a task, derived from the checklist markup in the party descriptions. Identity is the stable data-subtask-id the editor mints into the markup. */ Subtask[];
1127
1666
  assigned_to?: (string | /* Represents a variable assignment with its expression and optional resolved value. Used for dynamic user assignments that get resolved during workflow execution. */ VariableAssignment)[];
1128
1667
  ecp?: /* Details regarding ECP for the workflow step */ ECPDetails;
1129
1668
  installer?: /* Details regarding ECP for the workflow step */ ECPDetails;
@@ -1320,6 +1859,7 @@ declare namespace Paths {
1320
1859
  Components.Schemas.WorkflowDefinition;
1321
1860
  export type $400 = /* Standard error response returned when an API request fails. */ Components.Schemas.ErrorResp;
1322
1861
  export type $401 = /* Standard error response returned when an API request fails. */ Components.Schemas.ErrorResp;
1862
+ export type $409 = /* Standard error response returned when an API request fails. */ Components.Schemas.ErrorResp;
1323
1863
  export type $500 = /* Standard error response returned when an API request fails. */ Components.Schemas.ErrorResp;
1324
1864
  }
1325
1865
  }
@@ -1725,6 +2265,9 @@ interface OperationMethods {
1725
2265
  * that define the structure of the workflow. Once created, the definition can be used
1726
2266
  * to start workflow executions.
1727
2267
  *
2268
+ * Deprecated: from 17 October 2026 00:00 Europe/Berlin this endpoint answers 409 —
2269
+ * create a flow via `POST /v2/flows/templates` instead.
2270
+ *
1728
2271
  */
1729
2272
  'createDefinition'(
1730
2273
  parameters?: Parameters<UnknownParamsObject> | null,
@@ -1962,6 +2505,9 @@ interface PathsDictionary {
1962
2505
  * that define the structure of the workflow. Once created, the definition can be used
1963
2506
  * to start workflow executions.
1964
2507
  *
2508
+ * Deprecated: from 17 October 2026 00:00 Europe/Berlin this endpoint answers 409 —
2509
+ * create a flow via `POST /v2/flows/templates` instead.
2510
+ *
1965
2511
  */
1966
2512
  'post'(
1967
2513
  parameters?: Parameters<UnknownParamsObject> | null,
@@ -2193,8 +2739,13 @@ type Client = OpenAPIClient<OperationMethods, PathsDictionary>
2193
2739
  type ActionSchedule = Components.Schemas.ActionSchedule;
2194
2740
  type AgentConfig = Components.Schemas.AgentConfig;
2195
2741
  type AiAgentTask = Components.Schemas.AiAgentTask;
2742
+ type AiPrefillConfig = Components.Schemas.AiPrefillConfig;
2743
+ type AiPrefillExtractionField = Components.Schemas.AiPrefillExtractionField;
2744
+ type AiPrefillMapping = Components.Schemas.AiPrefillMapping;
2196
2745
  type AutomationConfig = Components.Schemas.AutomationConfig;
2746
+ type AutomationFailurePolicy = Components.Schemas.AutomationFailurePolicy;
2197
2747
  type AutomationInputContext = Components.Schemas.AutomationInputContext;
2748
+ type AutomationOutputContext = Components.Schemas.AutomationOutputContext;
2198
2749
  type AutomationTask = Components.Schemas.AutomationTask;
2199
2750
  type AutomationTrigger = Components.Schemas.AutomationTrigger;
2200
2751
  type ChangeReasonStatusReq = Components.Schemas.ChangeReasonStatusReq;
@@ -2213,11 +2764,15 @@ type DueDateConfig = Components.Schemas.DueDateConfig;
2213
2764
  type DynamicDueDate = Components.Schemas.DynamicDueDate;
2214
2765
  type ECPDetails = Components.Schemas.ECPDetails;
2215
2766
  type Edge = Components.Schemas.Edge;
2767
+ type EmailReviewConfig = Components.Schemas.EmailReviewConfig;
2216
2768
  type EnableRequirement = Components.Schemas.EnableRequirement;
2217
2769
  type EntitySync = Components.Schemas.EntitySync;
2218
2770
  type ErrorResp = Components.Schemas.ErrorResp;
2219
2771
  type EvaluationSource = Components.Schemas.EvaluationSource;
2772
+ type FlowContextSettings = Components.Schemas.FlowContextSettings;
2773
+ type FlowDisplayRule = Components.Schemas.FlowDisplayRule;
2220
2774
  type FlowLimitWarning = Components.Schemas.FlowLimitWarning;
2775
+ type FlowRuleAnchor = Components.Schemas.FlowRuleAnchor;
2221
2776
  type FlowTemplate = Components.Schemas.FlowTemplate;
2222
2777
  type FlowTemplateBase = Components.Schemas.FlowTemplateBase;
2223
2778
  type FlowTemplateId = Components.Schemas.FlowTemplateId;
@@ -2225,7 +2780,13 @@ type FlowTemplatesList = Components.Schemas.FlowTemplatesList;
2225
2780
  type ImmediateSchedule = Components.Schemas.ImmediateSchedule;
2226
2781
  type ItemType = Components.Schemas.ItemType;
2227
2782
  type JourneyAutomationTrigger = Components.Schemas.JourneyAutomationTrigger;
2783
+ type JourneyContextParameter = Components.Schemas.JourneyContextParameter;
2784
+ type JourneyContextUsage = Components.Schemas.JourneyContextUsage;
2785
+ type JourneyContextUsagesReq = Components.Schemas.JourneyContextUsagesReq;
2786
+ type JourneyContextUsagesResp = Components.Schemas.JourneyContextUsagesResp;
2228
2787
  type JourneySubmissionTrigger = Components.Schemas.JourneySubmissionTrigger;
2788
+ type MainContextAnchor = Components.Schemas.MainContextAnchor;
2789
+ type MainContextSetting = Components.Schemas.MainContextSetting;
2229
2790
  type ManualTask = Components.Schemas.ManualTask;
2230
2791
  type ManualTrigger = Components.Schemas.ManualTrigger;
2231
2792
  type MaxAllowedLimit = Components.Schemas.MaxAllowedLimit;
@@ -2233,14 +2794,17 @@ type Operator = Components.Schemas.Operator;
2233
2794
  type PartnerDetails = Components.Schemas.PartnerDetails;
2234
2795
  type Phase = Components.Schemas.Phase;
2235
2796
  type RelativeSchedule = Components.Schemas.RelativeSchedule;
2797
+ type RuleAnchor = Components.Schemas.RuleAnchor;
2236
2798
  type SearchFlowTemplates = Components.Schemas.SearchFlowTemplates;
2237
2799
  type Section = Components.Schemas.Section;
2800
+ type Stage = Components.Schemas.Stage;
2238
2801
  type Statement = Components.Schemas.Statement;
2239
2802
  type Step = Components.Schemas.Step;
2240
2803
  type StepDescription = Components.Schemas.StepDescription;
2241
2804
  type StepJourney = Components.Schemas.StepJourney;
2242
2805
  type StepRequirement = Components.Schemas.StepRequirement;
2243
2806
  type StepType = Components.Schemas.StepType;
2807
+ type Subtask = Components.Schemas.Subtask;
2244
2808
  type Task = Components.Schemas.Task;
2245
2809
  type TaskBase = Components.Schemas.TaskBase;
2246
2810
  type TaskType = Components.Schemas.TaskType;
@@ -2253,4 +2817,4 @@ type VariableAssignment = Components.Schemas.VariableAssignment;
2253
2817
  type Version = Components.Schemas.Version;
2254
2818
  type WorkflowDefinition = Components.Schemas.WorkflowDefinition;
2255
2819
 
2256
- export { type StepJourney as $, type ActionSchedule as A, type FlowTemplate as B, type Client as C, type DecisionTask as D, type ECPDetails as E, type FlowLimitWarning as F, type FlowTemplateBase as G, type FlowTemplateId as H, type FlowTemplatesList as I, type ImmediateSchedule as J, type ItemType as K, type JourneyAutomationTrigger as L, type JourneySubmissionTrigger as M, type ManualTask as N, type OperationMethods as O, Paths as P, type ManualTrigger as Q, type MaxAllowedLimit as R, type Operator as S, type PartnerDetails as T, type Phase as U, type RelativeSchedule as V, SearchFlowTemplates as W, type Section as X, type Statement as Y, type Step as Z, type StepDescription as _, Components as a, type StepRequirement as a0, type StepType as a1, type Task as a2, type TaskBase as a3, type TaskType as a4, type TimeUnit as a5, type Trigger as a6, type TriggerMode as a7, type TriggerType as a8, type UpdateEntityAttributes as a9, type VariableAssignment as aa, type Version as ab, type WorkflowDefinition as ac, type PathsDictionary as b, type AgentConfig as c, type AiAgentTask as d, type AutomationConfig as e, type AutomationInputContext as f, type AutomationTask as g, type AutomationTrigger as h, type ChangeReasonStatusReq as i, type ClosingReason as j, type ClosingReasonId as k, type ClosingReasonNotFoundResp as l, type ClosingReasons as m, type ClosingReasonsIds as n, type ClosingReasonsStatus as o, type Condition as p, CreateFlowTemplate as q, type DefinitionNotFoundResp as r, type DelayedSchedule as s, type DueDateConfig as t, type DynamicDueDate as u, type Edge as v, type EnableRequirement as w, type EntitySync as x, type ErrorResp as y, type EvaluationSource as z };
2820
+ export { type JourneySubmissionTrigger as $, type ActionSchedule as A, type Edge as B, type Client as C, type DecisionTask as D, type ECPDetails as E, type EmailReviewConfig as F, type EnableRequirement as G, type EntitySync as H, type ErrorResp as I, type EvaluationSource as J, type FlowContextSettings as K, type FlowDisplayRule as L, type FlowLimitWarning as M, type FlowRuleAnchor as N, type OperationMethods as O, Paths as P, type FlowTemplate as Q, type FlowTemplateBase as R, type FlowTemplateId as S, type FlowTemplatesList as T, type ImmediateSchedule as U, type ItemType as V, type JourneyAutomationTrigger as W, type JourneyContextParameter as X, type JourneyContextUsage as Y, type JourneyContextUsagesReq as Z, type JourneyContextUsagesResp as _, Components as a, type MainContextAnchor as a0, type MainContextSetting as a1, type ManualTask as a2, type ManualTrigger as a3, type MaxAllowedLimit as a4, type Operator as a5, type PartnerDetails as a6, type Phase as a7, type RelativeSchedule as a8, type RuleAnchor as a9, SearchFlowTemplates as aa, type Section as ab, type Stage as ac, type Statement as ad, type Step as ae, type StepDescription as af, type StepJourney as ag, type StepRequirement as ah, type StepType as ai, type Subtask as aj, type Task as ak, type TaskBase as al, type TaskType as am, type TimeUnit as an, type Trigger as ao, type TriggerMode as ap, type TriggerType as aq, type UpdateEntityAttributes as ar, type VariableAssignment as as, type Version as at, type WorkflowDefinition as au, type PathsDictionary as b, type AgentConfig as c, type AiAgentTask as d, type AiPrefillConfig as e, type AiPrefillExtractionField as f, type AiPrefillMapping as g, type AutomationConfig as h, type AutomationFailurePolicy as i, type AutomationInputContext as j, type AutomationOutputContext as k, type AutomationTask as l, type AutomationTrigger as m, type ChangeReasonStatusReq as n, type ClosingReason as o, type ClosingReasonId as p, type ClosingReasonNotFoundResp as q, type ClosingReasons as r, type ClosingReasonsIds as s, type ClosingReasonsStatus as t, type Condition as u, CreateFlowTemplate as v, type DefinitionNotFoundResp as w, type DelayedSchedule as x, type DueDateConfig as y, type DynamicDueDate as z };