---
title: "Update a flow"
method: PATCH
path: "/flows/{id}"
tags: ["Flows"]
---

# Update a flow

`PATCH /flows/{id}`

## Request

- Base URL: `https://sumgenius.ai/api/v1`
- URL: `https://sumgenius.ai/api/v1/flows/{id}`
- Auth: one of:
  - API key in header `X-SumGenius-Api-Key`
  - HTTP bearer

Rename, retarget channels, set the tag, and/or replace the definition. A new definition is saved as the DRAFT and validated the same way as on create; the live version keeps running until you publish. Positions are dropped when the definition changes (the builder re-lays it out). Requires the `write` scope.

## Path parameters

- `id` integer, required

## Request body

- FlowUpdate: Send only what should change.
  - `name` string
  - `definition` FlowDefinition: A flow as a graph. Read GET /flows/nodes for every node type, port and config field.
    - `trigger` FlowTrigger, required: What starts the flow. Also the config of node "1". Per-source fields are in GET /flows/nodes sources.*.config.
      - `source` 'dm' | 'comment' | 'ad_referral' | 'story_mention' | 'story_reply' | 'ig_reel_share' | 'ig_post_share' | 'ig_unsupported_attachment' | 'image_received' | 'audio_received' | 'video_received' | 'file_received' | 'ai_intent', required
      - `keywords` string[]: dm source: any of these starts the flow.
      - `match_type` 'contains' | 'exact'
      - `comment_trigger_id` integer, nullable: comment source, linked mode: a standalone comment trigger id.
      - `comment_keywords` string[]: comment source, native mode.
      - `comment_match_type` 'contains' | 'exact'
      - `comment_post_id` string, nullable
      - `ad_ref` string, nullable
      - `intent_description` string, nullable
    - `nodes` FlowNode[], required
      - `id` string, required: String id; "1" is the trigger.
      - `type` 'trigger' | 'message' | 'collect_input' | 'condition' | 'action' | 'delay' | 'ai_step' | 'ai_handoff' | 'randomizer' | 'book_appointment' | 'http_request' | 'goto_flow', required
      - `config` object: Per type; see GET /flows/nodes nodes.<type>.config.
    - `edges` FlowEdge[], required
      - `from` string, required
      - `from_port` string: One of the source node's output ports, for example output_1, output_2, output_timeout.
      - `to` string, required
      - `to_port` 'input_1'
  - `channels` string[]
  - `tag_id` integer, nullable

## Response `200`

OK

- object
  - `data` Flow, required
    - `id` integer
    - `name` string, nullable
    - `status` 'draft' | 'active' | 'paused'
    - `trigger_type` 'keyword' | 'first_message' | 'comment_trigger' | 'button_tap': Legacy column; reads keyword for nearly every flow. Use trigger.sources.
    - `trigger` object: What starts the flow. A comment source with mode linked belongs to a standalone comment trigger (see /comment-triggers); mode native means the flow matches its own keywords with no trigger row.
      - `sources` FlowTriggerSource[], required
        - `source` 'dm' | 'comment' | 'ai_intent' | 'story_mention' | 'story_reply' | 'ig_reel_share' | 'ig_post_share' | 'ig_unsupported_attachment'
        - `mode` 'linked' | 'native' | 'null', nullable: Comment sources only: linked (a standalone trigger) or native (the flow's own keywords).
        - `comment_trigger_id` integer, nullable: The linked trigger, when mode is linked.
        - `comment_trigger_name` string, nullable
        - `keywords` string[]
        - `match_type` string, nullable
        - `intent_description` string, nullable: ai_intent sources: what the AI is told to detect.
        - `output_port` string, nullable
        - `button_count` integer: Linked comment sources: how many trigger buttons branch the flow. Above zero means the flow starts on a button tap, not on the comment.
    - `channels` string[]: Empty means not narrowed.
    - `version` integer
    - `published_version` integer, nullable
    - `priority` integer, nullable
    - `stats` object
      - `entries` integer
      - `completions` integer
      - `completion_rate` number, nullable: Null when nobody entered.
    - `tag_id` integer, nullable: Single-flow responses only.
    - `definition` FlowDefinition: A flow as a graph. Read GET /flows/nodes for every node type, port and config field.
      - `trigger` FlowTrigger, required: What starts the flow. Also the config of node "1". Per-source fields are in GET /flows/nodes sources.*.config.
        - `source` 'dm' | 'comment' | 'ad_referral' | 'story_mention' | 'story_reply' | 'ig_reel_share' | 'ig_post_share' | 'ig_unsupported_attachment' | 'image_received' | 'audio_received' | 'video_received' | 'file_received' | 'ai_intent', required
        - `keywords` string[]: dm source: any of these starts the flow.
        - `match_type` 'contains' | 'exact'
        - `comment_trigger_id` integer, nullable: comment source, linked mode: a standalone comment trigger id.
        - `comment_keywords` string[]: comment source, native mode.
        - `comment_match_type` 'contains' | 'exact'
        - `comment_post_id` string, nullable
        - `ad_ref` string, nullable
        - `intent_description` string, nullable
      - `nodes` FlowNode[], required
        - `id` string, required: String id; "1" is the trigger.
        - `type` 'trigger' | 'message' | 'collect_input' | 'condition' | 'action' | 'delay' | 'ai_step' | 'ai_handoff' | 'randomizer' | 'book_appointment' | 'http_request' | 'goto_flow', required
        - `config` object: Per type; see GET /flows/nodes nodes.<type>.config.
      - `edges` FlowEdge[], required
        - `from` string, required
        - `from_port` string: One of the source node's output ports, for example output_1, output_2, output_timeout.
        - `to` string, required
        - `to_port` 'input_1'
    - `has_draft` boolean: Single-flow responses only.
    - `draft_behavior_changed` boolean: Single-flow responses only: the draft would behave differently from the live version.
    - `node_count` integer
    - `warnings` string[]: On writes only: non-blocking validation notes.
    - `created_at` string, date-time, nullable: UTC ISO-8601.
    - `updated_at` string, date-time, nullable: UTC ISO-8601.

## Other responses

- `400`: Error envelope. Codes: `invalid_param`: 400 a parameter or body field failed validation; `param` names it `invalid_json`: 400 the body is not valid JSON `invalid_idempotency_key`: 400 Idempotency-Key is not 1 to 128 printable ASCII characters `unauthorized`: 401 no API key sent `invalid_api_key`: 401 the key is not recognised `addon_inactive`: 403 the key is valid but the Webhook & API add-on is not active `insufficient_scope`: 403 the key scope does not cover this endpoint; carries `required_scope` and `key_scope` `feature_unavailable`: 403 the plan does not include this feature; `param` names it `already_blocked`: 409 that person is already on the AI blocklist `plan_limit_reached`: 403 the plan cap for this resource is reached (for example knowledge base items) `already_member`: 409 that email is already a team member `limit_reached`: 409 the product cap for this resource is reached (3 webhook endpoints, 10 active keys); remove one first `cannot_revoke_self`: 409 a key cannot revoke itself `too_soon`: 429 the same invitation was resent moments ago; the message says how long to wait `governance_incomplete`: 422 the endpoint cannot go live until its data-sharing declaration is attested with a purpose `invitation_pending`: 409 that email already has a pending invitation; resend or cancel it `not_found`: 404 missing, or not owned by your account `method_not_allowed`: 405 wrong method; the Allow header lists valid ones `idempotency_in_progress`: 409 a request with this Idempotency-Key is still running `resume_blocked`: 409 the AI pause on this conversation was set by a solicitation pause, a fraud flag or a connected-account pause; lift it from the portal `blocked`: 409 the customer is on the AI blocklist `opted_out`: 409 the customer opted out of automated messages `window_closed`: 409 the Meta messaging window for this conversation has closed `purge_active`: 409 SMS AI cannot be switched on while inbound body purge is on `sms_not_ready`: 409 SMS AI cannot be switched on until carrier registration assigns a Messaging Service `idempotency_key_reused`: 422 same Idempotency-Key, different request `unprocessable_send`: 422 a send was permanently rejected by the channel `rate_limited`: 429 quota or burst ceiling reached; Retry-After is set `service_unavailable`: 503 temporary failure; retry as directed `server_error`: 500 unexpected failure on our side `flow_conflict`: The trigger cannot be activated because of its linked flows: more than one, a paused one, or a broken link. The message says which. `not_connected`: The channel you asked about is not connected to this account. `not_pending`: The comment reply is not waiting for approval (already sent, rejected, or never queued). `send_failed`: 422 Meta refused the reply. The row is marked failed; the message has the reason. `slot_unavailable`: The requested time is outside business hours or already booked. The message says which. `missing_fields`: The account requires customer details this booking did not include; missing_fields lists them. `already_cancelled`: The appointment is already cancelled. `not_active`: Only a pending or confirmed appointment can be rescheduled. `not_editable`: The post is in a status that does not allow this: only draft, scheduled and failed posts can be edited or scheduled; published posts cannot be deleted; only scheduled posts can be unscheduled; only failed posts can be retried. `publish_failed`: 422 a platform rejected the post. The row is now failed; post.error_message and results say why. Retry with POST /posts/{id}/retry. `invalid_definition`: 422 the flow definition failed validation; errors lists every problem, warnings the non-blocking ones. `flow_blocked`: 409 the flow manager refused the action (for example no published version yet, a linked comment trigger in use, or a draft edited elsewhere); the message says why. `conflict`: 409 the draft was edited elsewhere since it was read.
- `401`: Error envelope. Codes: `invalid_param`: 400 a parameter or body field failed validation; `param` names it `invalid_json`: 400 the body is not valid JSON `invalid_idempotency_key`: 400 Idempotency-Key is not 1 to 128 printable ASCII characters `unauthorized`: 401 no API key sent `invalid_api_key`: 401 the key is not recognised `addon_inactive`: 403 the key is valid but the Webhook & API add-on is not active `insufficient_scope`: 403 the key scope does not cover this endpoint; carries `required_scope` and `key_scope` `feature_unavailable`: 403 the plan does not include this feature; `param` names it `already_blocked`: 409 that person is already on the AI blocklist `plan_limit_reached`: 403 the plan cap for this resource is reached (for example knowledge base items) `already_member`: 409 that email is already a team member `limit_reached`: 409 the product cap for this resource is reached (3 webhook endpoints, 10 active keys); remove one first `cannot_revoke_self`: 409 a key cannot revoke itself `too_soon`: 429 the same invitation was resent moments ago; the message says how long to wait `governance_incomplete`: 422 the endpoint cannot go live until its data-sharing declaration is attested with a purpose `invitation_pending`: 409 that email already has a pending invitation; resend or cancel it `not_found`: 404 missing, or not owned by your account `method_not_allowed`: 405 wrong method; the Allow header lists valid ones `idempotency_in_progress`: 409 a request with this Idempotency-Key is still running `resume_blocked`: 409 the AI pause on this conversation was set by a solicitation pause, a fraud flag or a connected-account pause; lift it from the portal `blocked`: 409 the customer is on the AI blocklist `opted_out`: 409 the customer opted out of automated messages `window_closed`: 409 the Meta messaging window for this conversation has closed `purge_active`: 409 SMS AI cannot be switched on while inbound body purge is on `sms_not_ready`: 409 SMS AI cannot be switched on until carrier registration assigns a Messaging Service `idempotency_key_reused`: 422 same Idempotency-Key, different request `unprocessable_send`: 422 a send was permanently rejected by the channel `rate_limited`: 429 quota or burst ceiling reached; Retry-After is set `service_unavailable`: 503 temporary failure; retry as directed `server_error`: 500 unexpected failure on our side `flow_conflict`: The trigger cannot be activated because of its linked flows: more than one, a paused one, or a broken link. The message says which. `not_connected`: The channel you asked about is not connected to this account. `not_pending`: The comment reply is not waiting for approval (already sent, rejected, or never queued). `send_failed`: 422 Meta refused the reply. The row is marked failed; the message has the reason. `slot_unavailable`: The requested time is outside business hours or already booked. The message says which. `missing_fields`: The account requires customer details this booking did not include; missing_fields lists them. `already_cancelled`: The appointment is already cancelled. `not_active`: Only a pending or confirmed appointment can be rescheduled. `not_editable`: The post is in a status that does not allow this: only draft, scheduled and failed posts can be edited or scheduled; published posts cannot be deleted; only scheduled posts can be unscheduled; only failed posts can be retried. `publish_failed`: 422 a platform rejected the post. The row is now failed; post.error_message and results say why. Retry with POST /posts/{id}/retry. `invalid_definition`: 422 the flow definition failed validation; errors lists every problem, warnings the non-blocking ones. `flow_blocked`: 409 the flow manager refused the action (for example no published version yet, a linked comment trigger in use, or a draft edited elsewhere); the message says why. `conflict`: 409 the draft was edited elsewhere since it was read.
- `403`: Error envelope. Codes: `invalid_param`: 400 a parameter or body field failed validation; `param` names it `invalid_json`: 400 the body is not valid JSON `invalid_idempotency_key`: 400 Idempotency-Key is not 1 to 128 printable ASCII characters `unauthorized`: 401 no API key sent `invalid_api_key`: 401 the key is not recognised `addon_inactive`: 403 the key is valid but the Webhook & API add-on is not active `insufficient_scope`: 403 the key scope does not cover this endpoint; carries `required_scope` and `key_scope` `feature_unavailable`: 403 the plan does not include this feature; `param` names it `already_blocked`: 409 that person is already on the AI blocklist `plan_limit_reached`: 403 the plan cap for this resource is reached (for example knowledge base items) `already_member`: 409 that email is already a team member `limit_reached`: 409 the product cap for this resource is reached (3 webhook endpoints, 10 active keys); remove one first `cannot_revoke_self`: 409 a key cannot revoke itself `too_soon`: 429 the same invitation was resent moments ago; the message says how long to wait `governance_incomplete`: 422 the endpoint cannot go live until its data-sharing declaration is attested with a purpose `invitation_pending`: 409 that email already has a pending invitation; resend or cancel it `not_found`: 404 missing, or not owned by your account `method_not_allowed`: 405 wrong method; the Allow header lists valid ones `idempotency_in_progress`: 409 a request with this Idempotency-Key is still running `resume_blocked`: 409 the AI pause on this conversation was set by a solicitation pause, a fraud flag or a connected-account pause; lift it from the portal `blocked`: 409 the customer is on the AI blocklist `opted_out`: 409 the customer opted out of automated messages `window_closed`: 409 the Meta messaging window for this conversation has closed `purge_active`: 409 SMS AI cannot be switched on while inbound body purge is on `sms_not_ready`: 409 SMS AI cannot be switched on until carrier registration assigns a Messaging Service `idempotency_key_reused`: 422 same Idempotency-Key, different request `unprocessable_send`: 422 a send was permanently rejected by the channel `rate_limited`: 429 quota or burst ceiling reached; Retry-After is set `service_unavailable`: 503 temporary failure; retry as directed `server_error`: 500 unexpected failure on our side `flow_conflict`: The trigger cannot be activated because of its linked flows: more than one, a paused one, or a broken link. The message says which. `not_connected`: The channel you asked about is not connected to this account. `not_pending`: The comment reply is not waiting for approval (already sent, rejected, or never queued). `send_failed`: 422 Meta refused the reply. The row is marked failed; the message has the reason. `slot_unavailable`: The requested time is outside business hours or already booked. The message says which. `missing_fields`: The account requires customer details this booking did not include; missing_fields lists them. `already_cancelled`: The appointment is already cancelled. `not_active`: Only a pending or confirmed appointment can be rescheduled. `not_editable`: The post is in a status that does not allow this: only draft, scheduled and failed posts can be edited or scheduled; published posts cannot be deleted; only scheduled posts can be unscheduled; only failed posts can be retried. `publish_failed`: 422 a platform rejected the post. The row is now failed; post.error_message and results say why. Retry with POST /posts/{id}/retry. `invalid_definition`: 422 the flow definition failed validation; errors lists every problem, warnings the non-blocking ones. `flow_blocked`: 409 the flow manager refused the action (for example no published version yet, a linked comment trigger in use, or a draft edited elsewhere); the message says why. `conflict`: 409 the draft was edited elsewhere since it was read.
- `404`: Error envelope. Codes: `invalid_param`: 400 a parameter or body field failed validation; `param` names it `invalid_json`: 400 the body is not valid JSON `invalid_idempotency_key`: 400 Idempotency-Key is not 1 to 128 printable ASCII characters `unauthorized`: 401 no API key sent `invalid_api_key`: 401 the key is not recognised `addon_inactive`: 403 the key is valid but the Webhook & API add-on is not active `insufficient_scope`: 403 the key scope does not cover this endpoint; carries `required_scope` and `key_scope` `feature_unavailable`: 403 the plan does not include this feature; `param` names it `already_blocked`: 409 that person is already on the AI blocklist `plan_limit_reached`: 403 the plan cap for this resource is reached (for example knowledge base items) `already_member`: 409 that email is already a team member `limit_reached`: 409 the product cap for this resource is reached (3 webhook endpoints, 10 active keys); remove one first `cannot_revoke_self`: 409 a key cannot revoke itself `too_soon`: 429 the same invitation was resent moments ago; the message says how long to wait `governance_incomplete`: 422 the endpoint cannot go live until its data-sharing declaration is attested with a purpose `invitation_pending`: 409 that email already has a pending invitation; resend or cancel it `not_found`: 404 missing, or not owned by your account `method_not_allowed`: 405 wrong method; the Allow header lists valid ones `idempotency_in_progress`: 409 a request with this Idempotency-Key is still running `resume_blocked`: 409 the AI pause on this conversation was set by a solicitation pause, a fraud flag or a connected-account pause; lift it from the portal `blocked`: 409 the customer is on the AI blocklist `opted_out`: 409 the customer opted out of automated messages `window_closed`: 409 the Meta messaging window for this conversation has closed `purge_active`: 409 SMS AI cannot be switched on while inbound body purge is on `sms_not_ready`: 409 SMS AI cannot be switched on until carrier registration assigns a Messaging Service `idempotency_key_reused`: 422 same Idempotency-Key, different request `unprocessable_send`: 422 a send was permanently rejected by the channel `rate_limited`: 429 quota or burst ceiling reached; Retry-After is set `service_unavailable`: 503 temporary failure; retry as directed `server_error`: 500 unexpected failure on our side `flow_conflict`: The trigger cannot be activated because of its linked flows: more than one, a paused one, or a broken link. The message says which. `not_connected`: The channel you asked about is not connected to this account. `not_pending`: The comment reply is not waiting for approval (already sent, rejected, or never queued). `send_failed`: 422 Meta refused the reply. The row is marked failed; the message has the reason. `slot_unavailable`: The requested time is outside business hours or already booked. The message says which. `missing_fields`: The account requires customer details this booking did not include; missing_fields lists them. `already_cancelled`: The appointment is already cancelled. `not_active`: Only a pending or confirmed appointment can be rescheduled. `not_editable`: The post is in a status that does not allow this: only draft, scheduled and failed posts can be edited or scheduled; published posts cannot be deleted; only scheduled posts can be unscheduled; only failed posts can be retried. `publish_failed`: 422 a platform rejected the post. The row is now failed; post.error_message and results say why. Retry with POST /posts/{id}/retry. `invalid_definition`: 422 the flow definition failed validation; errors lists every problem, warnings the non-blocking ones. `flow_blocked`: 409 the flow manager refused the action (for example no published version yet, a linked comment trigger in use, or a draft edited elsewhere); the message says why. `conflict`: 409 the draft was edited elsewhere since it was read.
- `409`: conflict.
- `422`: invalid_definition.
- `429`: Error envelope. Codes: `invalid_param`: 400 a parameter or body field failed validation; `param` names it `invalid_json`: 400 the body is not valid JSON `invalid_idempotency_key`: 400 Idempotency-Key is not 1 to 128 printable ASCII characters `unauthorized`: 401 no API key sent `invalid_api_key`: 401 the key is not recognised `addon_inactive`: 403 the key is valid but the Webhook & API add-on is not active `insufficient_scope`: 403 the key scope does not cover this endpoint; carries `required_scope` and `key_scope` `feature_unavailable`: 403 the plan does not include this feature; `param` names it `already_blocked`: 409 that person is already on the AI blocklist `plan_limit_reached`: 403 the plan cap for this resource is reached (for example knowledge base items) `already_member`: 409 that email is already a team member `limit_reached`: 409 the product cap for this resource is reached (3 webhook endpoints, 10 active keys); remove one first `cannot_revoke_self`: 409 a key cannot revoke itself `too_soon`: 429 the same invitation was resent moments ago; the message says how long to wait `governance_incomplete`: 422 the endpoint cannot go live until its data-sharing declaration is attested with a purpose `invitation_pending`: 409 that email already has a pending invitation; resend or cancel it `not_found`: 404 missing, or not owned by your account `method_not_allowed`: 405 wrong method; the Allow header lists valid ones `idempotency_in_progress`: 409 a request with this Idempotency-Key is still running `resume_blocked`: 409 the AI pause on this conversation was set by a solicitation pause, a fraud flag or a connected-account pause; lift it from the portal `blocked`: 409 the customer is on the AI blocklist `opted_out`: 409 the customer opted out of automated messages `window_closed`: 409 the Meta messaging window for this conversation has closed `purge_active`: 409 SMS AI cannot be switched on while inbound body purge is on `sms_not_ready`: 409 SMS AI cannot be switched on until carrier registration assigns a Messaging Service `idempotency_key_reused`: 422 same Idempotency-Key, different request `unprocessable_send`: 422 a send was permanently rejected by the channel `rate_limited`: 429 quota or burst ceiling reached; Retry-After is set `service_unavailable`: 503 temporary failure; retry as directed `server_error`: 500 unexpected failure on our side `flow_conflict`: The trigger cannot be activated because of its linked flows: more than one, a paused one, or a broken link. The message says which. `not_connected`: The channel you asked about is not connected to this account. `not_pending`: The comment reply is not waiting for approval (already sent, rejected, or never queued). `send_failed`: 422 Meta refused the reply. The row is marked failed; the message has the reason. `slot_unavailable`: The requested time is outside business hours or already booked. The message says which. `missing_fields`: The account requires customer details this booking did not include; missing_fields lists them. `already_cancelled`: The appointment is already cancelled. `not_active`: Only a pending or confirmed appointment can be rescheduled. `not_editable`: The post is in a status that does not allow this: only draft, scheduled and failed posts can be edited or scheduled; published posts cannot be deleted; only scheduled posts can be unscheduled; only failed posts can be retried. `publish_failed`: 422 a platform rejected the post. The row is now failed; post.error_message and results say why. Retry with POST /posts/{id}/retry. `invalid_definition`: 422 the flow definition failed validation; errors lists every problem, warnings the non-blocking ones. `flow_blocked`: 409 the flow manager refused the action (for example no published version yet, a linked comment trigger in use, or a draft edited elsewhere); the message says why. `conflict`: 409 the draft was edited elsewhere since it was read.

---

[API](https://skmtc.dev/sumgenius/apis/chatgenius-rest-api.md) · [All operations](https://skmtc.dev/sumgenius/apis/chatgenius-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sumgenius/apis/chatgenius-rest-api/revisions/f1621a748e6f?raw)