Skip to content
Try for free
On this page

Workflows

Rollback workflow

Activate a previous deployment version asynchronously, defaulting to the preceding active version. Requires workspace Admin access and a deployed workflow. The draft is unchanged. Poll the accepted `latestDeploymentAttempt`. To select a version while undeployed, use Activate workflow version. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:write`.

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

Activate a previous deployment version asynchronously, defaulting to the preceding active version. Requires workspace Admin access and a deployed workflow. The draft is unchanged. Poll the accepted latestDeploymentAttempt. To select a version while undeployed, use Activate workflow version. 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 deployment version to reactivate.

object

Optional deployment version to reactivate.

default
{}
1 field
versioninteger

Deployment version to reactivate. Omit to select the previous active version.

minimum
1
maximum
2147483647

Additional properties are not allowed.

Request example 1

json
{
  "version": 2
}

Responses

200

The accepted rollback attempt.

object

Current deployment state after accepting the rollback attempt.

1 field
dataobjectRequired

Response data.

7 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
versionintegerRequired

Deployment version selected for re-activation.

maximum
9007199254740991
exclusiveMinimum
0

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_01J8ZK4RX5N7Y3S0U8D6E1W2",
      "deploymentVersionId": "depver_01J8ZK4RX5N7Y3S0U8D6E1W3",
      "version": 2,
      "action": "activate",
      "status": "activating",
      "isCurrent": true,
      "readiness": {
        "webhooks": "ready",
        "schedules": "ready",
        "mcp": "not_applicable"
      },
      "requestedAt": "2026-06-12T10:30:00.000Z",
      "activatedAt": null,
      "error": null
    },
    "version": 2
  }
}

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