Skip to content

Workflows

Replace workflow state

Replace the draft graph in one write. Requires workspace write access. Concurrent row-locked writes are last-write-wins; IDs owned by another workflow return `409`. Deployments, schedules, and webhook registrations are unchanged. Deploy to serve the edits. Lint is advisory. Use `dryRun=true` to validate without saving, auditing, or notifying collaborators. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:write`.

PUT/api/v2/workflows/{workflowId}/state

Replace the draft graph in one write. Requires workspace write access. Concurrent row-locked writes are last-write-wins; IDs owned by another workflow return 409. Deployments, schedules, and webhook registrations are unchanged. Deploy to serve the edits.

Lint is advisory. Use dryRun=true to validate without saving, auditing, or notifying collaborators. 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

Query parameters

dryRunboolean

Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (409) as a committed write. needsRedeployment describes the pre-write state. For semantic operations, mintedBlockIds is empty; previewBlockIds contains provisional IDs with a warning, since committing mints new IDs.

Request body

Required

A complete replacement draft graph for a workflow.

object

A complete replacement draft graph for a workflow.

5 fields
blocksobjectRequired

Blocks keyed by block id.

Schema details
Additional propertiesobject

One node of a workflow graph and its configuration.

15 fields
idstringRequired

Block identifier, unique within the workflow.

minLength
1
typestringRequired

Registered block type.

minLength
1
namestringRequired

Block display name; must be unique within the workflow.

minLength
1
maxLength
255
positionobjectRequired

Canvas coordinates of a block.

2 fields
xnumberRequired

Canvas x coordinate.

ynumberRequired

Canvas y coordinate.

subBlocksobjectRequired

Configured inputs keyed by sub-block id.

Schema details
Additional propertiesobject

One configurable input on a block.

3 fields
idstringRequired

Sub-block identifier.

minLength
1
typestringRequired

Sub-block input type.

minLength
1
valuevalueRequired

Configured value; shape depends on the sub-block type.

outputsobjectRequired

Declared output shape keyed by output name.

Schema details
Additional propertiesvalue

Declared shape of one output; depends on the block type.

enabledbooleanRequired

Whether the block runs.

horizontalHandlesboolean

Whether edge handles render horizontally.

heightnumber

Rendered block height.