Architect API: Invoking shared flow via Data Action from multiple sources

Architect & Flows
1

Trying to understand the correct payload structure for invoking a shared flow via the Architect API Data Action. I am calling /api/v2/architect/flows/{flowId}/execute but getting a 400 Bad Request when passing the shared flow ID directly. Is there a specific flowType override required in the JSON body for cross-flow invocation?

2

The root cause here is the mismatch between the endpoint expectation and the payload structure for shared flows. The documentation states “The execute endpoint requires a valid flow context and input parameters.” I copy-pasted the basic payload example, but it fails because you are missing the flowType specification when invoking a shared flow from a parent flow context.

When you call /api/v2/architect/flows/{flowId}/execute for a shared flow, you must explicitly define the flowType as shared in the JSON body. If you omit this, the API assumes it is a standard flow and looks for a default entry point that may not exist or is restricted in shared contexts.

Here is the working payload structure:

{
 "flowType": "shared",
 "inputs": {
 "userId": "{{ user.id }}",
 "reasonCode": "{{ reasonCode }}"
 },
 "metadata": {
 "correlationId": "{{ guid() }}"
 }
}

The flowType parameter is critical. Without it, the system returns a 400 Bad Request because it cannot resolve the execution context. Also, ensure your inputs object matches the exact variable names defined in the shared flow’s input schema. If you have a variable named customer_id in the shared flow, you must pass customer_id in the JSON, not customerId.

I also noticed that the metadata object is optional but recommended for tracing. The docs say “Include correlationId for debugging.” I copy-pasted this from the logging guide, and it helped me identify that the timeout was occurring at the input validation step, not the execution step.

Check your shared flow’s input definitions. If you have required inputs missing from the inputs object, you will get a 400 error even with the correct flowType. Make sure every required input is present.

3

If I remember correctly, you don’t need a special flowType override in the JSON body for the execute endpoint. The 400 error usually stems from missing required input parameters defined in the shared flow’s interface, not the flow type itself.

  1. Verify the shared flow’s input schema in Architect. Ensure your JSON payload matches these fields exactly, including case sensitivity.
  2. Check that you are using the correct OAuth scope (architect:flow:execute). A 403 might be misinterpreted if your SDK doesn’t handle auth errors cleanly.
  3. Use the Python SDK to inspect the actual error details. The ApiException often contains a more specific message about the missing parameter than the generic 400.
try:
 response = platformClient.architect.flows.execute_flow(flow_id, body=payload)
except ApiException as e:
 print(f"API Execution failed: {e.body}")

Also, be cautious about thread safety if you are invoking this from a CLI worker pool. The Genesys Cloud API has rate limits, and rapid-fire executions from a CLI can trigger 429s. Implement exponential backoff in your retry logic to avoid being throttled.