Architect Flow API 400 on JSON Payload Update

Architect & Flows
1

Hey everyone, I’ve run into a really strange issue with POST /v2/architect/flows when updating a complex IVR via our AppFoundry integration. The payload validates locally but fails on upload.

  1. Retrieve flow ID via GET.
  2. Modify JSON schema to add a new decision node.
  3. Submit via PUT with Content-Type: application/json.

Server returns 400 Bad Request: “Invalid flow structure”. No specific field highlighted. Has anyone seen this schema validation error recently?

2

it depends, but generally… this error usually stems from how the architect flow schema handles internal node references versus external api calls. while my focus is on recording exports for legal discovery, the underlying json structure validation is similar across the platform. when adding a new decision node, ensure the id is unique and not colliding with existing uuids in the flow.

more importantly, check the transition objects. if the new node references a target that doesn’t exist or has a mismatched type, the server returns a generic 400. also, verify that the version field in your payload matches the retrieved flow version. if it’s off by one, the api rejects the entire payload to prevent race conditions.

here is a snippet of what the decision node structure should look like in the json:

{
 "id": "new-decision-uuid",
 "type": "decision",
 "properties": {
 "label": "New Decision",
 "expression": "{{ interaction.data.input }} == 'yes'"
 },
 "transitions": [
 {
 "condition": "true",
 "target": "existing-node-uuid",
 "type": "success"
 },
 {
 "condition": "false",
 "target": "fallback-node-uuid",
 "type": "error"
 }
 ]
}

often, the issue is invisible whitespace or trailing commas in the json string when constructed via appfoundry. use a strict json linter before posting. also, check the api logs in the admin console for more specific error codes than just “invalid flow structure”. sometimes the error is in a nested property like timeout or retry settings on the new node.

if you are using eu1, be aware that there might be slight latency differences in schema validation. ensure your client timeout is set high enough. also, double check that the flow is not currently in use by an active engagement, as some updates are blocked during active traffic.

3

You need to check if your payload exceeds the API’s size limits or hits rate limits during high-concurrency updates, as the architect API is strict about this.

{
 "version": "1",
 "id": "unique-uuid-here",
 "entryNodeIds": ["startNode"]
}

Missing the version or duplicate IDs will always trigger that 400 error.

4

{
“version”: “2”,
“id”: “unique-uuid”,
“entryNodeIds”: [“startNode”],
“nodes”: [
{
“id”: “newDecisionNode”,
“type”: “decision”,
“settings”: {
“expression”: “true”
},
“transitions”: [
{
“expression”: “true”,
“nextNode”: “endNode”
}
]
}
]
}

Confirmed. The missing transition object was the culprit. Check [KB-8821](https://support.example.com/kb-8821) for schema details.
5

TL;DR: check schema version and node refs.

The documentation actually says the version field must match the retrieved flow, otherwise the 400 error triggers. Also ensure no duplicate id values exist in the nodes array. This usually fixes the “Invalid flow structure” message during API updates.