This document describes the HTTP APIs for deploying workflows and managing deployment versions. Deployment creates a stable snapshot of a workflow that can be executed via API, webhooks, or schedules. For workflow execution APIs that consume deployed state, see Execution APIs For general workflow CRUD operations, see Workflow APIs
Workflows in Sim Studio maintain two parallel states to ensure development does not disrupt production:
| State Type | Purpose | Mutability | Execution Context |
|---|---|---|---|
| Draft State | Active development copy | Editable in UI | Manual/client-side runs |
| Deployed State | Production snapshot | Immutable per version | API, webhook, schedule triggers |
The deployment system ensures that production executions (triggered via public API, webhooks, or schedules) use a stable workflow definition, while development work continues independently in the draft state.
Deployment Architecture
Sources: apps/sim/app/api/workflows/[id]/deploy/route.ts:83-89, apps/sim/app/api/workflows/[id]/route.ts:85-111, apps/sim/hooks/queries/deployments.ts99-112
The deployment system uses versioned snapshots. Each deployment creates a new version record containing the complete workflow state at that moment.
Deployment Entity Relationship
The state JSON field in the deployment version contains a serialized snapshot of the WorkflowState, including blocks, edges, loops, and parallels.
Sources: apps/sim/app/api/workflows/[id]/deploy/route.ts:1-3, apps/sim/app/api/workflows/[id]/deploy/route.ts:50-56, apps/sim/hooks/queries/deployments.ts5-7
POST /api/workflows/[id]/deployCreates a new deployment version by snapshotting the current draft state. This endpoint triggers the performFullDeploy orchestration logic.
Request
Deployment Logic
validateWorkflowPermissions (requires admin access) apps/sim/app/api/workflows/[id]/deploy/route.ts:72-75.actorUserId from the session to attribute the deployment apps/sim/app/api/workflows/[id]/deploy/route.ts:77-81.performFullDeploy, which snapshots the normalized tables into a deployment version apps/sim/app/api/workflows/[id]/deploy/route.ts:83-89.Sources: apps/sim/app/api/workflows/[id]/deploy/route.ts:63-114
GET /api/workflows/[id]/deployRetrieves metadata including whether the workflow is currently deployed and if it needs redeployment.
Response
Sources: apps/sim/app/api/workflows/[id]/deploy/route.ts:19-61
PATCH /api/workflows/[id]/deployUpdates deployment settings, specifically the isPublicApi toggle which controls if a workflow can be executed without workspace-level authentication apps/sim/app/api/workflows/[id]/deploy/route.ts:116-157.
GET /api/workflows/[id]/deploymentsLists all historical deployment versions for a specific workflow. This is used in the DeployModal to allow users to see version history.
Sources: apps/sim/hooks/queries/deployments.ts141-155
The system detects if a workflow has changed since its last deployment by comparing the current draft state with the deployedState.
The logic resides in hasWorkflowChanged, which performs a deep comparison while ignoring non-functional changes like block positions, layout dimensions, or height apps/sim/lib/workflows/comparison/compare.ts25-30
Comparison Logic
type, name, enabled status, and data apps/sim/lib/workflows/comparison/compare.ts146-174position, layout, and height apps/sim/lib/workflows/comparison/compare.test.ts78-118Sources: apps/sim/lib/workflows/comparison/compare.ts58-71 apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/deploy/hooks/use-change-detection.ts:68-71
The DeployModal component provides the primary UI for managing these API interactions.
Deployment UI Entities
useDeployWorkflow: Mutation hook for the POST /deploy endpoint apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/deploy/components/deploy-modal/deploy-modal.tsx:174-174.useDeploymentInfo: Query hook for fetching deployment status apps/sim/hooks/queries/deployments.ts86-94useChangeDetection: A client-side hook that monitors local workflow state (from WorkflowStore and SubBlockStore) against the fetched deployedState apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/deploy/hooks/use-change-detection.ts:21-33.Deployment Pre-checks
Before calling the deploy API, the client runs runPreDeployChecks to ensure the workflow is valid for production apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/deploy/components/deploy-modal/deploy-modal.tsx:23-23.
Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/deploy/components/deploy-modal/deploy-modal.tsx:78-116, apps/sim/hooks/queries/deployments.ts15-34
| Error Code | Status | Meaning |
|---|---|---|
Unauthorized | 401 | User lacks permissions to deploy (requires admin role) apps/sim/app/api/workflows/[id]/deploy/route.ts:73-75 |
validation | 400 | Deployment failed due to workflow validation errors apps/sim/app/api/workflows/[id]/deploy/route.ts:93-94 |
not_found | 404 | Workflow record could not be found apps/sim/app/api/workflows/[id]/deploy/route.ts:93-94 |
Public API disabled | 403 | Attempted to set isPublicApi to true when restricted by enterprise access control apps/sim/app/api/workflows/[id]/deploy/route.ts:141-142 |
Sources: apps/sim/app/api/workflows/[id]/deploy/route.ts:109-113, apps/sim/app/api/workflows/[id]/deploy/route.ts:152-156
Refresh this wiki