--- title: "Save Clarity Process Snapshot" method: POST path: "/v2/clarity-v2/processes/{process_id}/snapshots/{kind}/save" tags: ["ClarityV2"] --- # Save Clarity Process Snapshot `POST /v2/clarity-v2/processes/{process_id}/snapshots/{kind}/save` ## Request - Base URL: `https://api.duvo.ai` - URL: `https://api.duvo.ai/v2/clarity-v2/processes/{process_id}/snapshots/{kind}/save` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Save user edits as the live Clarity v2 snapshot for the selected kind. ## Path parameters - `process_id` string, uuid, required - `kind` 'current_process' | 'transformation_proposal', required ## Request body - object - `steps` union[], required - union - object - `id` string, required: Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice" - `targetSteps` object[], required: Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true. - `stepId` string, required: Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice" - `label` string, nullable, required: Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise" - `isDefault` boolean, required: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. - `title` string, required: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". - `action` string, nullable, required: Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order." - `role` string, nullable, required: Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System" - `system` string, nullable, required: System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null - `input` string, nullable, required: Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number" - `output` string, nullable, required: What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature" - `exception` string, nullable, required: Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match" - `handling` string, nullable, required: How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved" - `assumptions` string[], nullable, required: Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"] - `openQuestions` string[], nullable, required: Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"] - `confidence` 'low' | 'medium' | 'high', required: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. - `nodeType` 'event', required - `nodeSubtype` 'start' | 'end' | 'timer' | 'message' | 'escalation', required: BPMN event subtype. "start" (entry trigger), "end" (terminal state), "timer" (time-based wait), "message" (external communication), "escalation" (route to higher authority). - `description` string, nullable, required: Optional prose describing what happens at this event. May be null for structural markers. - `rationale` string, nullable, required: Optional reason for the event's existence. May be null for structural markers. - `sources` object[], required: Evidence supporting this event. Empty array allowed (structural markers carry no evidence); non-empty values must follow the source schema. - `attribution` string, required: Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12" - `excerpt` string, required: Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice." - `captureId` string: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. - `evidenceId` string: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. - `locator` union: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. - object - … - object - … - object - … - object - … - object - … - object - … - `sourceConfidence` 'low' | 'medium' | 'high': Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. - `resolutionStatus` 'resolved' | 'unresolved' | 'legacy' | 'manual': Resolution status for the structured source link. Legacy sources may omit this field. - `condition` string, nullable, required: Always null on events; included for shape compatibility across variants. - `extraCaptureNeeded` object, nullable - `id` string, uuid, required: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. - `gap` string, required: Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don't know which fields the AP analyst copies from the invoice into NetSuite." - `proposal` string, nullable: What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check." - `readiness` 'low' | 'medium' | 'high', nullable: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. - `readinessRationale` string, nullable: One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures." - object - `id` string, required: Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice" - `targetSteps` object[], required: Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true. - `stepId` string, required: Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice" - `label` string, nullable, required: Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise" - `isDefault` boolean, required: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. - `title` string, required: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". - `action` string, nullable, required: Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order." - `role` string, nullable, required: Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System" - `system` string, nullable, required: System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null - `input` string, nullable, required: Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number" - `output` string, nullable, required: What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature" - `exception` string, nullable, required: Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match" - `handling` string, nullable, required: How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved" - `assumptions` string[], nullable, required: Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"] - `openQuestions` string[], nullable, required: Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"] - `confidence` 'low' | 'medium' | 'high', required: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. - `nodeType` 'task', required - `nodeSubtype` 'user' | 'service' | 'send' | 'receive' | 'manual' | 'businessRule' | 'script', required: BPMN task subtype. "user" (human work), "service" (automated/API call), "send"/"receive" (messaging), "manual" (offline physical work), "businessRule" (rule engine), "script" (code execution). - `description` string, required: Full prose paragraph describing what happens in this step in natural language. Used for documentation reconstruction. Example: "Finance reviews the invoice in NetSuite, checking line item accuracy and matching against the purchase order before flagging for approval." - `rationale` string, required: Why this step exists in the process — its purpose or business reason. Used by downstream agents to assess whether the step is essential or removable. Example: "Catches mispriced line items before they reach the customer and prevents downstream credit notes." - `sources` object[], required: Evidence supporting this step's existence and details. At least one source is required — every step must trace back to something in the captures. - `attribution` string, required: Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12" - `excerpt` string, required: Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice." - `captureId` string: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. - `evidenceId` string: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. - `locator` union: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. - object - … - object - … - object - … - object - … - object - … - object - … - `sourceConfidence` 'low' | 'medium' | 'high': Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. - `resolutionStatus` 'resolved' | 'unresolved' | 'legacy' | 'manual': Resolution status for the structured source link. Legacy sources may omit this field. - `condition` string, nullable, required: Optional precondition that gates this task. Null when the task is unconditional. Example: "Only when invoice total exceeds $10,000" - `extraCaptureNeeded` object, nullable - `id` string, uuid, required: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. - `gap` string, required: Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don't know which fields the AP analyst copies from the invoice into NetSuite." - `proposal` string, nullable: What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check." - `readiness` 'low' | 'medium' | 'high', nullable: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. - `readinessRationale` string, nullable: One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures." - object - `id` string, required: Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice" - `targetSteps` object[], required: Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true. - `stepId` string, required: Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice" - `label` string, nullable, required: Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise" - `isDefault` boolean, required: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. - `title` string, required: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". - `action` string, nullable, required: Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order." - `role` string, nullable, required: Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System" - `system` string, nullable, required: System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null - `input` string, nullable, required: Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number" - `output` string, nullable, required: What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature" - `exception` string, nullable, required: Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match" - `handling` string, nullable, required: How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved" - `assumptions` string[], nullable, required: Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"] - `openQuestions` string[], nullable, required: Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"] - `confidence` 'low' | 'medium' | 'high', required: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. - `nodeType` 'gateway', required - `nodeSubtype` 'exclusive' | 'parallel' | 'inclusive', required: BPMN gateway subtype. "exclusive" (XOR — exactly one branch taken), "parallel" (AND — all branches taken), "inclusive" (OR — one or more branches taken). - `description` string, required: Full prose describing the decision logic at this gateway. - `rationale` string, required: Why this branching decision exists in the process. - `sources` object[], required: Evidence supporting the decision criteria. - `attribution` string, required: Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12" - `excerpt` string, required: Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice." - `captureId` string: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. - `evidenceId` string: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. - `locator` union: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. - object - … - object - … - object - … - object - … - object - … - object - … - `sourceConfidence` 'low' | 'medium' | 'high': Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. - `resolutionStatus` 'resolved' | 'unresolved' | 'legacy' | 'manual': Resolution status for the structured source link. Legacy sources may omit this field. - `condition` string, required: Decision criteria evaluated at this gateway. BPMN requires this on every branching gateway. Existing rows persisted with null/empty values parse as "unknown" via a read-side preprocess; producers should write a real condition string going forward. - `extraCaptureNeeded` object, nullable - `id` string, uuid, required: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. - `gap` string, required: Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don't know which fields the AP analyst copies from the invoice into NetSuite." - `proposal` string, nullable: What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check." - `readiness` 'low' | 'medium' | 'high', nullable: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. - `readinessRationale` string, nullable: One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures." - `baselineSnapshotId` string, uuid, required - `clarityCurrentProcessId` string, uuid - `swot` object, nullable: SWOT analysis produced by the swot-analysis postprocessing agent. `undefined` = agent has not yet run; `null` = agent ran and produced no analysis. - `strengths` string[], required: Internal advantages of the current process — capabilities, resources, or design choices that work in its favour today. Phrase each as a short, evidence-backed statement. Example: "Bartenders know regulars by name, which keeps service personal during peak hours." - `weaknesses` string[], required: Internal limitations of the current process — gaps, inefficiencies, or fragile assumptions visible in how it runs today. Phrase each as a short, evidence-backed statement. Example: "Manual pour times balloon during rushes because there is only one tap." - `opportunities` string[], required: External openings the current process could exploit — adjacent automations, scale effects, or unmet needs surfaced by the captures. Example: "POS data could feed dynamic pricing for slow hours." - `threats` string[], required: External risks that could degrade the current process — regulatory, operational, technological, or human factors visible in the captures. Example: "New ID-check legislation will require staff to interrupt every order." - `summary` string, nullable: One short paragraph (3-5 sentences) describing the captured process at a glance. Surfaced at the top of the current-process tab so reviewers can orient themselves before scanning the steps. Example: "Customers order beer at the bar; the bartender greets them, picks an option matching their preference, pours and garnishes the glass, then rings the order through the POS before serving." - `projectedImpact` string, nullable: Answer-first, MECE-structured business case. 4-8 sentences of prose + one markdown assumptions table. Null when team context is insufficient to produce any quantitative or qualitative assessment. ## Response `201` Default Response - object - `snapshot` union, required - object - `id` string, uuid, required: Snapshot id - `process_id` string, uuid, required: Parent clarity_process id - `source_snapshot_id` 'null', nullable, required - `parent_id` string, uuid, nullable, required: Parent snapshot this row forked from, if any - `created_at` string, required: ISO 8601 creation timestamp - `updated_at` string, required: ISO 8601 last-update timestamp - `status` 'live' | 'historic' | 'draft' | 'generating', required: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. - `creator_type` 'human' | 'ai', required: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). - `user_id` string, uuid, nullable, required: Creator user id (the human who edited or triggered the run). - `sandbox_id` string, nullable, required: E2B sandbox id that produced AI rows; null for user edits. - `last_session_id` string, nullable, required: Claude SDK session id for artifact-chat follow-up reuse. - `kind` 'current_process', required - `data` object, required: Opaque BPMN payload describing the captured current process. - `version` integer, required: Schema version for the current process data payload. Increment on breaking changes to the data shape so consumers can branch on the version field. - `steps` union[], required: Ordered steps describing how the process works today, extracted from captures. Array position is the canonical order; BPMN topology is encoded by each step's targetSteps[] edges. - union - object - … - object - … - object - … - `swot` object, nullable: SWOT analysis produced by the swot-analysis postprocessing agent. `undefined` = agent has not yet run; `null` = agent ran and produced no analysis. - `strengths` string[], required: Internal advantages of the current process — capabilities, resources, or design choices that work in its favour today. Phrase each as a short, evidence-backed statement. Example: "Bartenders know regulars by name, which keeps service personal during peak hours." - `weaknesses` string[], required: Internal limitations of the current process — gaps, inefficiencies, or fragile assumptions visible in how it runs today. Phrase each as a short, evidence-backed statement. Example: "Manual pour times balloon during rushes because there is only one tap." - `opportunities` string[], required: External openings the current process could exploit — adjacent automations, scale effects, or unmet needs surfaced by the captures. Example: "POS data could feed dynamic pricing for slow hours." - `threats` string[], required: External risks that could degrade the current process — regulatory, operational, technological, or human factors visible in the captures. Example: "New ID-check legislation will require staff to interrupt every order." - `summary` string, nullable: One short paragraph (3-5 sentences) describing the captured process at a glance. Surfaced at the top of the current-process tab so reviewers can orient themselves before scanning the steps. Example: "Customers order beer at the bar; the bartender greets them, picks an option matching their preference, pours and garnishes the glass, then rings the order through the POS before serving." - object - `id` string, uuid, required: Snapshot id - `process_id` string, uuid, required: Parent clarity_process id - `source_snapshot_id` string, uuid, required - `parent_id` string, uuid, nullable, required: Parent snapshot this row forked from, if any - `created_at` string, required: ISO 8601 creation timestamp - `updated_at` string, required: ISO 8601 last-update timestamp - `status` 'live' | 'historic' | 'draft' | 'generating', required: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. - `creator_type` 'human' | 'ai', required: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). - `user_id` string, uuid, nullable, required: Creator user id (the human who edited or triggered the run). - `sandbox_id` string, nullable, required: E2B sandbox id that produced AI rows; null for user edits. - `last_session_id` string, nullable, required: Claude SDK session id for artifact-chat follow-up reuse. - `kind` 'transformation_proposal', required - `data` object, required: Opaque BPMN payload for the proposed transformed process. - `version` integer, required: Schema version for the transformation proposal data payload. Increment on breaking changes to the data shape so consumers can branch on the version field. - `steps` union[], required: Ordered steps describing the proposed redesigned process. Same shape as the current process steps; BPMN topology is encoded by each step's targetSteps[] edges. - union - object - … - object - … - object - … - `summary` string, nullable: One short paragraph (3-5 sentences) describing the proposed transformed process at a glance. Surfaced at the top of the transformation-proposal tab so reviewers can orient themselves before scanning the steps. Example: "Customers self-order on a tablet at the bar; a smart tap auto-pours the chosen beer into a labelled glass, which the customer collects from the pickup counter once payment clears." - `projectedImpact` string, nullable: Answer-first, MECE-structured business case. 4-8 sentences of prose + one markdown assumptions table. Null when team context is insufficient to produce any quantitative or qualitative assessment. ## Other responses - `400`: Default Response - `401`: Default Response - `403`: Default Response - `404`: Default Response - `409`: Default Response - `500`: Default Response --- [API](https://skmtc.dev/duvo/apis/duvo-public-api.md) - [All operations](https://skmtc.dev/duvo/apis/duvo-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/duvo/apis/duvo-public-api/revisions/dafcf3d868a9?raw)