Skip to content
Try for free
On this page

Workflows

Deploy workflow

Create a deployment version and activate it asynchronously. Requires workspace Admin access. Each accepted deploy creates a new version; retrying after a timeout can create a duplicate. Poll Get workflow deployment for the accepted `latestDeploymentAttempt` before treating the version as live. `lint` reports advisory findings for this version and never blocks deployment. A conflicting webhook path returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:write`.

POST/api/v2/workflows/{workflowId}/deploy

Create a deployment version and activate it asynchronously. Requires workspace Admin access. Each accepted deploy creates a new version; retrying after a timeout can create a duplicate. Poll Get workflow deployment for the accepted latestDeploymentAttempt before treating the version as live.

lint reports advisory findings for this version and never blocks deployment. A conflicting webhook path returns 409. Workspace API keys return 403; use a personal API key or scoped OAuth token.

OAuth scope: api:write.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:write

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:write.

Path parameters

workflowIdstringRequired

Unique workflow identifier.

minLength
1

Request body

Optional metadata for the new deployment version.

object

Optional metadata for the new deployment version.

default
{}
2 fields
namestring

Optional label for the deployment version.

minLength
1
maxLength
100
descriptionvalue

Optional release note for the deployment version.

Schema details

Any of

Option 1string
maxLength
50000
Option 2null

Additional properties are not allowed.

Request example 1

json
{
  "name": "Escalation routing",
  "description": "Adds the priority escalation branch."
}

Responses

200

The accepted deployment attempt.

object

Current deployment state after accepting the attempt.

1 field
dataobjectRequired

Response data.

8 fields
idstringRequired

Unique workflow identifier.

isDeployedbooleanRequired

Whether a workflow version is currently live and available for API execution.

deployedAtvalueRequired

ISO 8601 timestamp associated with the deployment, or null when unavailable.

format
date-time
Schema details

Any of

Option 1string
Option 2null
warningsarrayRequired

Non-fatal warnings about deployment side effects, such as notifications that are still queued or failed. Empty when there is nothing to report. Lint findings are never reported here.

Schema details
Array itemstring
activeDeploymentvalueRequired

Currently live deployment version, or null while no version is active.

Schema details

Any of

Option 1object

Summary of the workflow version currently serving API executions.

3 fields
deploymentVersionIdstringRequired

Identifier of the active deployment version.

versionintegerRequired

Numeric active deployment version.

maximum
9007199254740991
exclusiveMinimum
0
deployedAtstringRequired

ISO 8601 timestamp when this version became active.

format
date-time

Additional properties are not allowed.

Option 2null
latestDeploymentAttemptvalueRequired

Most recent deployment lifecycle attempt, or null when none is available.

Schema details

Any of

Option 1object

Lifecycle state of a deployment or version-activation attempt.

10 fields
idstringRequired

Unique deployment operation identifier.

deploymentVersionIdstringRequired

Deployment version targeted by this operation.

versionintegerRequired

Numeric deployment version.

maximum
9007199254740991
exclusiveMinimum
0
actionstringRequired

Operation being performed on the deployment version.

enum
["deploy","activate"]
statusstringRequired

Current deployment lifecycle status.

enum
["preparing","activating","active","failed","superseded"]
isCurrentbooleanRequired

Whether this operation still describes the current deployment attempt.

default
true
readinessobjectRequired

Readiness of the side effects required to activate a deployment.

3 fields
webhooksstringRequired

Webhook synchronization readiness.

enum
["pending","ready","not_applicable"]
schedulesstringRequired

Schedule synchronization readiness.

enum
["pending","ready","not_applicable"]
mcpstringRequired

MCP synchronization readiness.

enum
["pending","ready","not_applicable"]

Additional properties are not allowed.

requestedAtstringRequired

ISO 8601 timestamp when the deployment operation was requested.

format
date-time
activatedAtvalue

ISO 8601 activation timestamp, or null before activation completes.

format
date-time
Schema details

Any of

Option 1string
Option 2null
errorvalue

Deployment failure details, or null when no failure occurred.

Schema details

Any of

Option 1object

Failure details for a deployment lifecycle operation.

3 fields
codestringRequired

Stable deployment failure code.

messagestringRequired

Human-readable deployment failure message.

retryablebooleanRequired

Whether retrying the deployment may succeed.

Additional properties are not allowed.

Option 2null

Additional properties are not allowed.

Option 2null
versioninteger

Deployment version created for this attempt, when available.

maximum
9007199254740991
exclusiveMinimum
0
lintvalueRequired

Advisory lint for the admitted version, checked as the deploying member. Findings never block deployment. Null when lint exceeds its time budget or cannot complete; the deployment proceeds.

Schema details

Any of

Option 1object

Advisory findings about a saved graph. Findings never block a write or a deploy; they tell a caller what will misbehave at run time.

11 fields
sourcesarrayRequired

Blocks with no incoming edge. A trigger block is naturally a source; anything else here is unreachable.

Schema details
Array itemobject
3 fields
blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

sinksarrayRequired

Blocks with no outgoing edge.

Schema details
Array itemobject
3 fields
blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

orphanBlocksarrayRequired

Blocks with neither an incoming nor an outgoing edge.

Schema details
Array itemobject
3 fields
blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

emptyOutgoingPortsarrayRequired

Branch and container ports that lead nowhere.

Schema details
Array itemobject
5 fields
blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
handlestringRequired

Source handle with nothing connected to it.

labelstringRequired

Human-readable name of the port.

Additional properties are not allowed.

invalidBranchPortsarrayRequired

Condition and router edges whose source handle names no real branch.

Schema details
Array itemobject
5 fields
blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
sourceHandlestringRequired

Source handle that does not match the block.

reasonstringRequired

Why the handle is not valid for this block.

Additional properties are not allowed.

invalidConnectionTargetsarrayRequired

Edges pointing at a block that cannot legally receive them.

Schema details
Array itemobject
5 fields
sourceBlockIdstringRequired

Block the edge leaves.

sourceBlockNamevalueRequired

Display name of the source block.

Schema details

Any of

Option 1string
Option 2null
sourceHandlevalueRequired

Handle the edge leaves from.

Schema details

Any of

Option 1string
Option 2null
targetBlockIdstringRequired

Block the edge points at.

reasonstringRequired

Why the target is not a legal destination.

Additional properties are not allowed.

fieldIssuesarrayRequired

Per-block configuration problems. The most actionable part of the report for a headless graph builder: a block missing a required field will fail at run time.

Schema details
Array itemobject
5 fields
blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
missingRequiredFieldsarrayRequired

Required sub-block fields that resolve empty in the active mode.

Schema details
Array itemstring
inactiveModeValuesarrayRequired

Values stranded on the inactive member of a canonical pair.

Schema details
Array itemobject
4 fields
canonicalIdstringRequired

Canonical parameter the two sub-block modes share.

activeMemberIdvalueRequired

Sub-block the runtime reads, where the value should live.

Schema details

Any of

Option 1string
Option 2null
inactiveMemberIdstringRequired

Sub-block holding the stranded value, which the runtime ignores.

kindstringRequired

What kind of value is stranded.

enum
["credential","resource","other"]

Additional properties are not allowed.

Additional properties are not allowed.

unresolvedReferencesarrayRequired

Credential, resource, tool, and skill references that do not resolve; block-output references that will not work as written: a block that does not exist, or an output field the block does not have (reason unknown-field); and text outputs written unquoted in a JSON field (reason unquoted-json-string), which leave the field invalid JSON at run time unless the text is itself JSON. These values are still persisted; they are reported, not dropped.

Schema details
Array itemobject
7 fields
blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
fieldstringRequired

Sub-block field holding the reference.

valuevalueRequired

The reference, or references, that did not resolve.

Schema details

Any of

Option 1string
Option 2array
Schema details
Array itemstring
kindstringRequired

What kind of entity the reference was expected to name.

enum
["credential","resource","custom-tool","mcp-tool","skill","block-output"]
reasonstringRequired

Why the reference does not resolve.

Additional properties are not allowed.

tableFieldIssuesarrayRequired

Table block filter and order fields checked against the bound table's live schema that name no column (nor the implicit id, createdAt, updatedAt). Such a run fails inside the block's error edge. A filter holding a <block.output> reference, or one that is not JSON, is not checked.

Schema details
Array itemobject
5 fields
blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string
Option 2null
fieldstringRequired

The filter or sort field that names no column.

tableNamestringRequired

Display name of the table the block is bound to.

Additional properties are not allowed.

manualRunIssuevalueRequired

Why a manual run from the editor's Run button would be refused before it starts: no enabled trigger it can start from, more than one API trigger, or a selected trigger with no outgoing connection. The API run endpoints do not apply these checks. null when no manual-run issue is reported: the run can begin, only a chat trigger can start the workflow, or the graph is empty (reported in notes instead).

Schema details

Any of

Option 1object
5 fields
reasonstringRequired

Why the run is refused.

enum
["no-trigger","multiple-api-triggers","trigger-not-connected"]
messagestringRequired

The error the manual run raises.

blockIdvalueRequired

Trigger the run would start from, when the problem is that trigger.

Schema details

Any of

Option 1string
Option 2null
blockNamevalueRequired

Display name of that trigger.

Schema details

Any of

Option 1string
Option 2null
blockTypevalueRequired

Registered type of that trigger.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Option 2null
notesarrayRequired

Advisory notes about the report itself.

Schema details
Array itemstring

Additional properties are not allowed.

Option 2null

Additional properties are not allowed.

Additional properties are not allowed.

Response example 1

json
{
  "data": {
    "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
    "isDeployed": false,
    "deployedAt": null,
    "warnings": [],
    "activeDeployment": null,
    "latestDeploymentAttempt": {
      "id": "depop_01J8ZK3QW4M6X2R9T7B5C0V1",
      "deploymentVersionId": "depver_01J8ZK3QW4M6X2R9T7B5C0V2",
      "version": 3,
      "action": "deploy",
      "status": "preparing",
      "isCurrent": true,
      "readiness": {
        "webhooks": "pending",
        "schedules": "ready",
        "mcp": "not_applicable"
      },
      "requestedAt": "2026-06-12T10:30:00.000Z",
      "activatedAt": null,
      "error": null
    },
    "version": 3,
    "lint": {
      "sources": [],
      "sinks": [],
      "orphanBlocks": [],
      "emptyOutgoingPorts": [],
      "invalidBranchPorts": [],
      "invalidConnectionTargets": [],
      "fieldIssues": [],
      "unresolvedReferences": [],
      "tableFieldIssues": [],
      "manualRunIssue": null,
      "notes": []
    }
  }
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit