quick question about the platform api. calling put /api/v2/architect/flows is throwing a 400 bad request with code invalid_flow_definition. we are trying to update the telephony action for our apac byoc trunks. the json payload validates fine in the gui but the api rejects it. using sdk v2.5.1.
Ah, this is a recognized issue…
{
"actions": [
{
"name": "SetTelephonyTrunk",
"uuid": "your-action-uuid",
"trunk": {
"id": "trunk-uuid-from-api",
"type": "byoc"
},
"settings": {
"outboundCall": true
}
}
]
}
The error invalid_flow_definition usually stems from a mismatch between the UI’s simplified object structure and the strict API schema requirements. The GUI often accepts partial payloads or resolves trunk references internally, but the PUT /api/v2/architect/flows endpoint demands a complete, validated JSON structure.
When updating BYOC trunks via API, ensure the trunk object includes the explicit type field set to "byoc". Missing this causes the schema validator to reject the definition, even if the id is correct. Additionally, verify that the settings object is present. If you are modifying an existing action, include the uuid of the action itself. The API cannot infer which action to update without it.
Another common pitfall is using the trunk’s display name instead of its UUID in the id field. The API requires the raw UUID. You can retrieve this by calling GET /api/v2/architect/telephony/trunks.
For bulk updates, consider exporting the current flow via GET /api/v2/architect/flows/{flowId}, modifying the specific action node in the JSON, and then re-uploading. This preserves all other configuration details and prevents accidental overwrites of unrelated flow logic. Always validate the full flow JSON against the OpenAPI spec before sending. The SDK might mask some validation errors, so checking the raw response body provides clearer insights into which specific field failed validation.