Workflows

Endpoints under /api/v1/workflows. Send Authorization: Bearer. Missing/invalid token → 401. Workflow in another workspace → 403 { error: "API key cannot access this workflow" }. Missing workflow → 404.

Execute additionally requires a workspace-scoped key (403 "A workspace API key is required.").

There is no v1 collaboration API (canvas CRDT is tRPC only). Execute-step and pin-data are session /api/workflows/{id}/... only.

Endpoints

Create, import, or duplicate

POST /api/v1/workflows branches on the JSON body (all fields optional):

Empty body → blank workflow. 201. Single create: { workflow, links, ...syncedTriggers } (templates may also return chat thread fields). Bundle: { bundle, workflows[] } with importAction, importReadiness, bundleSubWorkflowStatus, links. links point at version, validate, execute, status, and portable export URLs.

POST /api/v1/workflows/import-preview — importJson or importBundleJson required (400 otherwise). Does not persist. See Importing n8n.

Update, get, and delete

GET → { workflow, links } or portable { name, description, nodes, edges }.

PATCH accepts name, description, status (draft | deployed | disabled), nodes[], edges[], importJson, trashed. Invalid status → 400. status: "deployed" runs deploy and returns the deploy failure payload on 400. Import-replace forces draft and returns importReadiness. trashed: true/false uses the trash path (in-memory trash on Prisma — see Recently deleted). DELETE → { deleted: true }.

PATCH does not accept versionMode / collaborationSessionId (those are tRPC workflows.update only).

Execute and status

POST /api/v1/workflows/{id}/execute — input?, startNodeId?, dryRun?, target? (active | candidate), executionTargetId?, expectedVersionId?, confirm?. Public API calls target active by default. Idempotency-Key supported. 202 { run, execution, queued: true, statusUrl, cancelUrl } when BullMQ accepted the job; 201 when inline (no Redis, E2E mode, or dry run). execution and run.executionEvidence identify requestedTarget, versionId, resourceMode (simulated | workspace-live), and reviewIdentity.

Repeating a completed request with the same key, principal and input returns the original execution receipt, even if the destination has since stopped or its candidate changed. It does not execute again. Use a new key for a new execution; current version, destination and approval checks then apply. Agent execute, test and step tools follow the same replay rule.

executionTargetId selects a named preview or production destination. Its active version must have a current approval and enabled deployment for live execution. Simulations use that destination's candidate and retain its identity in execution.destination; live runs include run.executionTarget. Reusing a key for a different destination, expected version or API principal returns a conflict. A foreign or unavailable destination does not select production instead. The typed workflows.execute tool accepts the same ID.

Candidate calls default to dry run. Live candidate execution requires dryRun: false, confirm: true, and the matching expectedVersionId. It uses real workspace resources; it is not an isolated runtime. Testing candidate v2 never changes active v1. Only deploy promotes a version.

GET /api/v1/workflows/{id}/status?runId= → { workflow, projection, run, status, queued, active, output, error, steps[], logs (last 20), links, pollAfterMs }. projection is the discriminator { kind: "workflow-status", version: 1, redacted }; keys without workspace.secret.read receive redacted: true and the safe run/workflow DTOs only (never inputs, outputs, errors, logs, node configuration, or credentials). active is true for queued | running | waiting. Unknown run → 404. Omit runId → { workflow, runs, statuses } (limit 20).

Deploy

Production and named previews

GET /api/v1/workflows/{id}/targets lists destination identities, candidate/active pointers, revisions and enabled state. It does not return connection secrets or draft graphs. Add ?includeHistory=true to include the latest 30 production activations in history, with activationId, targetId, versionId, numbered version, displayLabel, createdAt and canPrepareRollback. This flag identifies snapshots that can enter rollback preparation; current AIMS, connection and Git checks still decide whether publication is allowed.

POST /api/v1/workflows/{id}/targets accepts { "confirm": true, "change": { "action": "…" } } and requires an Idempotency-Key header (or idempotencyKey body field). The authenticated key needs write and execute authority. The key is bound to the authenticated principal, workflow and exact change. Replaying it returns the same receipt; a different change or principal returns 409.

Preparation keeps the current deployment running. A rollback preparation also preserves the editor candidate and returns preparedPublicationVersionId; use that historical version when requesting its approval and publication. Publication verifies the destination's current AIMS authority, Git evidence, connections and dependencies. API calls cannot grant approval. A production rollback can reuse only an approval explicitly permitting reactivation of that snapshot; otherwise prepare it and complete a new decision in Approvals.

POST /api/v1/workflows/{id}/targets/preview-publication accepts the publish fields without action and requires execute authority. It returns { ready, checks, warnings, connections, dependencies }: checks report blockers, warnings identify overlapping event sources, connections contain credential references (never secret values), and dependencies identify pinned child deployments. It is a read-only readiness check, not permission to skip revalidation on publish.

The equivalent tools are workflows.targets, workflows.preview-target-publication and workflows.update-target (with the same change object). MCP publication additionally requires its existing AIMS service-token and deployment-role checks. workflows.test and workflows.execute-step accept executionTargetId; step execution rejects a source run from another destination. Live steps run the destination's approved active version.

Legacy production transport

POST /api/v1/workflows/{id}/deploy validates readiness, pins the synchronized candidate, provisions a webhook, and syncs triggers. Success includes { workflow, synchronizedVersionId, webhookUrl, links: { webhook, invoke }, ...syncedTriggers }. Repository review blocks use workflow_review_not_synced, workflow_candidate_changed, or workflow_reviewed_version_unavailable. Other deploy failures → 400 with the public readiness payload.

Validate and review

GET|POST /api/v1/workflows/{id}/validate → { report, deploymentReadiness } (public: no internal env dump). POST validates a draft body without saving.

GET|POST .../review and GET|POST .../sync-from-repo: Versions & Git Review. Review POST: Member+. Sync POST: Admin/Owner.

POST /api/v1/workflows/validate-artifact { files } object or array (400 if missing).

Credentials

POST .../credentials/test → connection probe results for imported aliases. POST .../credentials/bootstrap-from-env → public bootstrap (no secret values). Workspace-wide n8n bootstrap: /api/v1/workers/n8n/credentials/bootstrap-from-env.

MCP

GET|POST /api/v1/workflows/mcp/{workspaceId}/{serverSlug} serves the workflow MCP server for that workspace slug. It always requires a bearer workspace-scoped API key bound to the stored workflow server workspace. Initialize, discovery, and listing require current read authority; tool calls require current execute authority. Personal and copilot keys are rejected, and revoked or downgraded keys lose authority at use time.

Next steps