---
title: "Validate a flow definition"
method: POST
path: "/flows/validate"
tags: ["Flows"]
---

# Validate a flow definition

`POST /flows/validate`

## Request

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

Dry run of the same validation create and update apply. Nothing is saved. Requires the `write` scope.

## Request body

- FlowValidateRequest
  - `definition` FlowDefinition, required: 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[]

## Response `200`

OK

- object
  - `data` FlowValidation, required
    - `valid` boolean
    - `errors` string[]
    - `warnings` string[]

## 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.
- `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)