Skip to content
Try for free
On this page

Workflows

Create workflow

Create an undeployed workflow at the workspace root or in a workflow folder. Requires workspace write access.

POST/api/v2/workflows

Create an undeployed workflow at the workspace root or in a workflow folder. Requires workspace write access.

The response includes the seeded start block and its ID for connecting other blocks. A name already used in the destination folder returns 409. Workspace folder trees exceeding 10,000 folders return 413.

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.

Request body

Required

Name, description, workspace, and optional folder for a new workflow.

object

Name, description, workspace, and optional folder for a new workflow.

4 fields
workspaceIdstringRequired

Workspace in which to create the workflow.

minLength
1
maxLength
128
namestringRequired

Workflow name.

minLength
1
maxLength
255
descriptionvalue

Optional workflow description.

Schema details

Any of

Option 1string
maxLength
50000
Option 2null
folderPathstring

Folder path. A missing leading slash is normalized before validation. Segments are percent-encoded, so a folder shown as "New folder" is /New%20folder: everything outside A-Z a-z 0-9 - _ . ~ is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal . or .. segment are rejected. At most 64 segments and 4096 encoded bytes.

maxLength
4096

Additional properties are not allowed.

Request example 1

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "name": "Customer support triage",
  "folderPath": "/Operations"
}

Behavior

The response includes the seeded start block and its ID for connecting other blocks. A name already used in the destination folder returns 409. Workspace folder trees exceeding 10,000 folders return 413.

Responses

201

The created workflow.

object

The created workflow and the blocks it was seeded with.

1 field
dataobjectRequired

Response data.

13 fields
idstringRequired

Unique workflow identifier.

webUrlstringRequired

Canonical absolute URL for opening this resource in the Sim web application.

format
uri
namestringRequired

Workflow name.

descriptionvalueRequired

Workflow description, or null when none is set.

Schema details

Any of

Option 1string
Option 2null
folderPathstringRequired

Canonical containing-folder path; / is the workspace root.

maxLength
4096
workspaceIdstringRequired

Workspace that owns the workflow.

isDeployedbooleanRequired

Whether the workflow has an active deployment.

deployedAtvalueRequired

ISO 8601 activation timestamp, or null when not deployed.

format
date-time
Schema details

Any of

Option 1string
Option 2null
runCountintegerRequired

Settled runs — completed, failed, or cancelled — counted as each one finishes; a paused run is counted once it settles. The counter is never reduced when a run ages out of log retention, so it can exceed the results returned by List workflow runs.

minimum
0
maximum
9007199254740991
lastRunAtvalueRequired

ISO 8601 timestamp of the latest settled run, whatever its outcome, or null when the workflow has never run.

format
date-time
Schema details

Any of

Option 1string
Option 2null
createdAtstringRequired

ISO 8601 timestamp when the workflow was created.

format
date-time
updatedAtstringRequired

ISO 8601 timestamp when the workflow was last updated.

format
date-time
blocksarrayRequired

Blocks seeded into the new workflow. Contains the start block; attach edges to its id.

Schema details
Array itemobject

A block the platform placed in a newly created workflow.

3 fields
idstringRequired

Block identifier.

typestringRequired

Registered block type.

namestringRequired

Block display name.

Additional properties are not allowed.

Additional properties are not allowed.

Additional properties are not allowed.

Response example 1

json
{
  "data": {
    "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
    "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
    "name": "Customer support triage",
    "description": "Routes incoming support requests to the right team.",
    "folderPath": "/Operations",
    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
    "isDeployed": false,
    "deployedAt": null,
    "runCount": 0,
    "lastRunAt": null,
    "createdAt": "2026-05-01T09:00:00.000Z",
    "updatedAt": "2026-08-09T18:04:11.000Z",
    "blocks": [
      {
        "id": "start-1",
        "type": "starter",
        "name": "Start"
      }
    ]
  }
}

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