FAQ
Install and run
Section titled “Install and run”How do I verify that an installation is healthy?
Section titled “How do I verify that an installation is healthy?”Check /health for liveness and /api/v1/platform/diagnostics for readiness; the diagnostics endpoint returns 200 for a healthy installation. See Installation & First Boot.
Why does diagnostics return 503?
Section titled “Why does diagnostics return 503?”The platform is running but is not yet ready, usually because extensions are still loading or the storage directory is unreachable. Wait 5–10 seconds, then check the logs as described in Troubleshooting.
Why does a REST flow run return an ID instead of the output?
Section titled “Why does a REST flow run return an ID instead of the output?”REST flow runs are asynchronous by default and return a run ID as plain text, while the CLI and MCP run-flow calls wait for typed output. See Running Flows for the synchronous REST alternative and ways to read results and logs.
Flows and connectors
Section titled “Flows and connectors”How do I select a connector action in a step?
Section titled “How do I select a connector action in a step?”Import the connector family in using: and name its action in invoke:, such as postgresql.query. The connector manifest is the source of truth for exact fields; see the Connector Catalog.
Why is there no generic result field on a connector output?
Section titled “Why is there no generic result field on a connector output?”Connectors declare descriptive output names such as body, rows or path; reference the exact name in the connector’s output schema. See Connector Catalog: Output field names.
How do I disable a flow without removing its definition?
Section titled “How do I disable a flow without removing its definition?”Set the flow’s status: to disabled; inactive is rejected at runtime. See The Shape of a Flow.
How do branch and environment selectors differ when running a flow?
Section titled “How do branch and environment selectors differ when running a flow?”The branch segment in the URL selects the version of the definitions, while --env or environment= selects the systems the run talks to. See Running Flows.
AI and MCP
Section titled “AI and MCP”Which field contains the text returned by ai.call?
Section titled “Which field contains the text returned by ai.call?”The generated text is in content, with other output fields including finishReason and token counts. Reference the step’s content field as shown in AI Connectors.
How can an MCP assistant inspect an installation while diagnosing a flow?
Section titled “How can an MCP assistant inspect an installation while diagnosing a flow?”The MCP channel provides read-entity, list-entities and the connector catalog alongside run-flow. An assistant can use the flow’s typed signature and live metadata; see Running Flows.
Security
Section titled “Security”What should I check when every request returns 401 or 403?
Section titled “What should I check when every request returns 401 or 403?”Authentication may be enabled without a supplied credential. Configure an API key, or disable authentication for an evaluation as described in Troubleshooting.
When does a rotated secret take effect?
Section titled “When does a rotated secret take effect?”Write the new value to the same secret path; runs starting after that write use the new value. A running flow keeps the values resolved at its start; see Secrets.
Can an automation account run flows without the admin role?
Section titled “Can an automation account run flows without the admin role?”A custom role can grant flow:run without Admin for a least-privilege automation account. See Roles for the role model and how to check your current role.
Help and licensing
Section titled “Help and licensing”How do I report a bug or request a feature from an installation?
Section titled “How do I report a bug or request a feature from an installation?”Use submit-support-request for problems and questions, or submit-feature-request for missing capabilities; REST equivalents are also documented. These channels attach the installation’s environment fingerprint and enter the triage queue, as explained in Troubleshooting.
Do environments and branches count as additional licensed connections?
Section titled “Do environments and branches count as additional licensed connections?”A connection is the licensing-counted unit; environments and branches are free structure layered on top. See Connections for how these pieces fit together.