Automation Code Workflows

Author a code workflow once as a plain automation project and serve it to every connected user by reference, deployed through the embedded bridge.

An automation code workflow lets you author a code workflow

a ProjectHandler artifact, the same contract a standalone automation project uses - and make it invocable by your connected users, without hand-authoring it in the visual Automation Workflow editor and without giving every connected user their own private copy.

The artifact itself says nothing about being "embedded". What makes it embedded-servable is which endpoint you deploy it through:

POST /api/automation/v1/projects/deploy creates a plain automation project. Nothing about it is reachable from embedded.
POST /api/embedded/internal/automation/projects/deploy deploys the identical artifact behind the embedded catalog - an internal, ADMIN-only surface with the same Java-hardening posture (BYTECHEF_WORKFLOW_CODE_WORKFLOW_JAVA_ENABLED, the Espresso sandbox loader) as /integrations/deploy. The multipart field is projectFile.

Deploy once, reference per user

Unlike the visual bridge - where each connected user gets their own copy of a workflow template

a code workflow is deployed once into a shared catalog project, and every connected user holds a reference to it. Code is not something a connected user can edit per-user, so a copy would only duplicate the same container for no benefit.

Practically:

The catalog project is resolved (or created, on first deploy) by name, hidden behind the same __EMBEDDED_AUTOMATION__ marker convention the visual bridge uses to keep the underlying automation Project out of view.
Redeploying the same artifact upgrades every referencing user's workflow at once - there is no per-user version pinning and no per-user bespoke deploy. If you need to stage a change, stage it in a separate environment before deploying to the one your customers use.
A workflow keeps the same identity (its ProjectWorkflow uuid) across redeploys as long as its name doesn't change, so existing references keep pointing at the right workflow after an upgrade.

The project appears in the same catalog listing as visual workflow templates, distinguished by a kind field:

kind: "COPY" - a visual template; provisioning creates a per-user copy.
kind: "REFERENCE" - a code workflow; provisioning creates a per-user reference to the shared, deploy-once workflow.

Invocation - the same two endpoints, the same rules

Automation code workflows are invoked through the existing embedded public endpoints - there is no new invocation surface:

Sync - POST /api/embedded/v1/workflows/{workflowUuid}, addressed by the workflow's catalog uuid. Requires a Request trigger, the same contract integration workflows follow - see Request Triggers for the trigger operations, the response and the errors.
Async - POST /api/embedded/v1/app-events. Requires the App Event trigger. Every enabled, non-dangling reference whose workflow declares that trigger fires when the connected user's app event is posted, alongside their integration workflows.

Deploy-time validation is advisory, not a hard rejection: a workflow with neither trigger still deploys, but the server logs a warning that it will never be reachable from either endpoint.

Both endpoints resolve the whole bridge, not just code-workflow references: the async endpoint's fan-out iterates every ConnectedUserProjectWorkflow row for the connected user, firing both reference-mode rows (code workflows) and copy-mode rows (visual bridge copies, addressed by the copy's own workflow uuid, not the template's). The sync endpoint resolves the same shapes against a single workflowUuid: a connected user's own copy uuid dispatches directly; a catalog uuid the user holds a reference to runs that reference; a catalog template uuid the user has already copied runs their copy. Anything else returns 404 - see No provisioning on first call below.

No provisioning on first call

Neither invocation endpoint creates anything. A catalog workflow uuid the connected user has no reference to and no copy of returns 404 from the sync endpoint, and the async endpoint only iterates rows that already exist. Provision the reference (below), or copy the template with POST /automation/workflow-templates/{workflowUuid}/copy, before the first call.

Explicit provisioning

Provision a reference before the connected user's first call:

POST /api/embedded/v1/{externalUserId}/automation/workflow-templates/{workflowUuid}/provision
X-Environment: PRODUCTION

ByteChef wires each of the workflow's connections from the connected user's existing connections, matched by component. To choose connections instead, send them keyed by component name in an optional body: {"connections": {"slack": 42}}. Components you leave out are auto-matched.

The same body can carry the workflow's input values, keyed by input name: {"connections": {"slack": 42}, "inputs": {"channel": "#alerts"}}. They are stored before the reference is enabled, so a workflow with required inputs comes out enabled in one call. When you send inputs, they replace the values already stored for the reference.

If every required component resolves to a connection, the reference is created enabled.
If a component has no matching connection, the reference is still created - left disabled - and the call returns HTTP 409 with {"missingConnectionComponentName": "slack"}.
If a required workflow input has no value yet (neither sent in inputs nor stored), the reference is created disabled and the call returns 204. Store the value, then enable the reference (next section).
A requested connection that isn't one of the connected user's connections returns 400. A catalog workflow the connected user can't see returns 404.

Calling provision again for an existing reference doesn't re-run auto-wiring. It only catches the reference up to the last published version and, if the body names connections or inputs, applies them. It keeps the reference's enabled state.

De-provisioning removes the reference (and its per-node connection wiring) outright:

DELETE /api/embedded/v1/{externalUserId}/automation/workflow-templates/{workflowUuid}/provision

Enabling, disabling and inputs

A reference is addressed by its catalog workflow uuid on the same workflow endpoints a copy uses:

DELETE /api/embedded/v1/{externalUserId}/automation/workflows/{workflowUuid}/enable disables the reference and keeps it, with its connections and input values.
POST /api/embedded/v1/{externalUserId}/automation/workflows/{workflowUuid}/enable enables it. The reference first catches up to the catalog project's last published version, then its connections are resolved again against the connected user's current connections - so a connection created after provisioning is picked up here. A missing connection returns 409 {"missingConnectionComponentName": ...}, a required input without a value returns 409 {"missingInputName": ...}, and the reference stays disabled.
PUT /api/embedded/v1/{externalUserId}/automation/workflows/{workflowUuid}/inputs stores the connected user's input values, with an inputs object keyed by input name. On an enabled reference, a change that leaves a required input without a value is rejected with 409 {"missingInputName": ...}.

Enabling a dangling reference, or storing inputs on one, fails with an error naming the reference as dangling. The frontend routes (without {externalUserId}, with the end user's JWT) behave the same.

Dangling references

If a published version no longer contains a workflow a connected user is referencing, or the catalog project is deleted, their reference doesn't silently disappear and doesn't silently keep running against a nonexistent workflow. It flips to a dangling state and is disabled:

Invisible to both invocation endpoints - a dangling reference behaves exactly like a disabled one to a caller (same 404, no existence leak).
Still listed for the connected user, carrying a reason: "Removed from the catalog project on publish" when a published version drops the workflow, or "The catalog project was deleted".
The connected user's connection configuration is preserved on the row, so nothing is lost even though the row itself stops being usable.

Dangling is permanent for that reference row - nothing currently clears the flag, and enabling it fails. Disabling a dangling reference removes its deployment entry but keeps the row. Uuid carry-forward only spans one deploy of history: if you restore a same-named workflow in a later deploy (after an intervening deploy that dropped it), the restored workflow gets a new uuid, not the one the dangling reference still points at. Recovering means de-provisioning the dangling reference and provisioning a fresh one against the workflow's new uuid - the connection auto-wiring runs again from scratch, so nothing carries over automatically.

Dangling only ever compares one catalog project's previous deploy against its current one - a redeploy of one catalog project never dangles a reference into a different catalog project.

Limits

No per-user version pinning. A redeploy upgrades every referencing user at once; there's no way to keep one connected user on an older version of the workflow while others move to a new one.
No per-user editing. A reference has no definition of its own - the workflow update/edit APIs reject reference rows outright. If a connected user needs their own customized copy, that's what the visual bridge's copy-mode is for.
Catalog projects are not editable in the code editor. The in-app code workflow editor excludes bridge catalog projects from its project list and rejects saves on them: an editor draft would interleave containers into the same deploy history the bridge's one-deploy-back uuid carry-forward reads, minting new workflow uuids on the next redeploy and permanently dangling connected-user references. The only write path for a catalog project is the deploy endpoint itself.
Resolution differs by kind. A code-workflow reference always resolves to the catalog project's last published workflow. A visual copy resolves to its own, independently deployed workflow - the connected user's copy, not the template it was copied from. Two connected users calling the same catalog uuid on a code workflow always run the same (latest) logic; two connected users who each copied the same template can be running different versions if one of them edited their copy since.