Skip to content
Try for free
On this page

Workflows

Import workflow

Create an undeployed workflow from a portable export object, bare draft state, or JSON string. Requires workspace write access. The empty-state example creates a draft that needs runnable blocks before execution. Mapped imports require a preview with the same choices, its `previewFingerprint`, and a stable `requestId`. Unresolved required configuration creates nothing. Identical retries return the committed result; reusing the ID with changed inputs returns `409`. The result includes regenerated graph IDs and an operation receipt. Workspace folder trees exceeding 10,000 folders return `413`. OAuth scope: `api:write`.

POST/api/v2/workflows/import

Create an undeployed workflow from a portable export object, bare draft state, or JSON string. Requires workspace write access. The empty-state example creates a draft that needs runnable blocks before execution.

Mapped imports require a preview with the same choices, its previewFingerprint, and a stable requestId. Unresolved required configuration creates nothing. Identical retries return the committed result; reusing the ID with changed inputs returns 409. The result includes regenerated graph IDs and an operation receipt. 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

Workflow document, destination, and optional reviewed mappings. This example creates an empty draft.

object

Workflow document, destination, and optional reviewed mappings. This example creates an empty draft.

10 fields
workspaceIdstringRequired

Workspace in which to import the workflow.

minLength
1
maxLength
128
workflowvalueRequired

Workflow export object, bare workflow state, or JSON string containing either form.

Schema details

Any of

Option 1string

JSON string containing a workflow export object or bare workflow state.

minLength
1
Option 2object

Workflow export object or bare workflow state.

folderPathstring

Destination folder path; omit for the workspace root.

maxLength
4096
namestring

Override for the imported workflow name.

minLength
1
maxLength
200
descriptionstring

Override for the imported workflow description.

maxLength
2000
mappingsarray

Mapping entries addressed by resource kind and source identifier.

maxItems
5000
Schema details
Array itemobject
3 fields
kindstringRequired

Resource or operation kind.

enum
["credential","env-var","knowledge-base","knowledge-document","table","file","file-folder","mcp-server","custom-tool","custom-block","skill","sandbox","workflow"]
sourceIdstringRequired

Untrusted source reference label; imports never use it to authorize or query a source workspace.

minLength
1
maxLength
4096
targetIdvalueRequired

Authorized destination identifier, or null to clear the mapping.

Schema details

Any of

Option 1string
minLength
1
maxLength
4096
Option 2null

Additional properties are not allowed.

bindingsarray

Resolved and unresolved source occurrences with their destination selections.

maxItems
5000
Schema details
Array itemobject
7 fields
blockIdstringRequired

Source block identifier before graph ID regeneration.

minLength
1
maxLength
256
subBlockKeystringRequired

Registered source field key, including the tool index for nested Agent fields.

minLength
1
maxLength
256
valuePatharray

Path within the field value; strings address properties and numbers address array entries.

default
[]
maxItems
8
Schema details
Array itemvalue
Schema details

Any of

Option 1string
minLength
1
maxLength
256
Option 2integer
minimum
0
maximum
2000
positionsarray

Positions occupied by this identifier in a multi-value field.

maxItems
2000
Schema details
Array iteminteger
minimum
0
maximum
2000
encodingstring

Registered encoding used to discover and rewrite the reference.

default
scalar
enum
["scalar","array","csv","files","environment"]
kindstringRequired

Resource or operation kind.

enum
["credential","env-var","knowledge-base","knowledge-document","table","file","file-folder","mcp-server","custom-tool","custom-block","skill","sandbox","workflow"]
targetIdvalueRequired

Authorized destination identifier, or null to clear the mapping.

Schema details

Any of

Option 1string
minLength
1
maxLength
4096
Option 2null

Additional properties are not allowed.

dependentValuesarray

Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated.

maxItems
2000
Schema details
Array itemobject
3 fields
blockIdstringRequired

Source block identifier before graph ID regeneration.

minLength
1
maxLength
256
subBlockKeystringRequired

Registered source field key, including the tool index for nested Agent fields.

minLength
1
maxLength
256
valuestringRequired

Destination value for the registered dependent field.

maxLength
16384

Additional properties are not allowed.

requestIdstring

Stable client request ID for mapped import. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can create another workflow.

minLength
1
maxLength
128
pattern
^[A-Za-z0-9._:-]+$
previewFingerprintstring

Fingerprint returned by an import preview with the same choices. A changed plan returns 409; preview again. Do not invent this value.

pattern
^[a-f0-9]{64}$

Additional properties are not allowed.

Request example 1

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "name": "Support draft",
  "workflow": {
    "blocks": {},
    "edges": []
  }
}

Responses

201

The imported workflow.

object

The workflow created by the import.

1 field
dataobjectRequired

Response data.

22 fields
idstringRequired

Resource identifier.

namestringRequired

Display name of the workflow or workspace.

descriptionvalueRequired

Imported workflow description.

Schema details

Any of

Option 1string
Option 2null
workspaceIdstringRequired

Explicit current workspace scope.

folderPathstringRequired

Canonical containing-folder path.

maxLength
4096
createdAtstringRequired

ISO 8601 timestamp when the workflow was imported.

format
date-time
updatedAtstringRequired

ISO 8601 timestamp when the workflow was last updated.

format
date-time
blocksarray

Blocks the import created, in payload order. Omitted only when replaying an older receipt that did not record this summary. The workflow state read returns the current full graph.

Schema details
Array itemobject

A block the import created in the new workflow.

3 fields
idstringRequired

Block identifier.

typestringRequired

Registered block type.

namestringRequired

Block display name.

Additional properties are not allowed.

warningsarrayRequired

Missing required workspace bindings, such as a table or knowledge base, reported as <block name>: <field> was stripped by export; set it before running. Set these fields before execution. Default exports clear workspace bindings; includeWorkspaceBindings=true retains non-secret bindings for same-workspace imports. Empty when no required binding is missing.

Schema details
Array itemstring
operationIdstring

Durable operation identifier to use for polling.

minLength
1
maxLength
256
requestIdstring

Client request ID used to commit this operation. Reuse identical mutation inputs with this ID after an uncertain response.

minLength
1
maxLength
128
kindstring

Type of committed workspace operation.

enum
["workflow_import","workspace_fork","workspace_push","workspace_pull"]
appliedboolean

The business transaction committed, including when follow-up work fails.

const
true
statusstring

Operation status; failed follow-up work does not undo the committed transaction.

enum
["processing","completed","completed_with_warnings","requires_configuration","failed"]
resourceIdsarray

Identifiers of resources created or changed by the committed operation.

maxItems
5000
Schema details
Array itemstring
minLength
1
maxLength
256
issuesarray

Structured warnings, missing configuration, and follow-up failures.

maxItems
2000
Schema details
Array itemobject
5 fields
codestringRequired

Stable machine-readable issue code.

minLength
1
maxLength
128
messagestringRequired

Human-readable explanation of the issue.

maxLength
2048
workflowIdstring

Workflow affected by this issue or deployment attempt.

maxLength
256
blockIdstring

Source block identifier before graph ID regeneration.

maxLength
256
subBlockKeystring

Registered source field key, including the tool index for nested Agent fields.

maxLength
256

Additional properties are not allowed.

idMapobject

Source graph identifiers mapped to the imported identifiers.

Schema details
Additional propertiesstring
maxLength
256
deploymentOperationIdsarray

Exact deployment attempts admitted by the workspace operation.

maxItems
1000
Schema details
Array itemstring
maxLength
256
deploymentsarray

Readiness of the exact admitted deployment attempts.

maxItems
1000
Schema details
Array itemobject
6 fields
operationIdstringRequired

Durable operation identifier to use for polling.

maxLength
256
workflowIdstringRequired

Workflow affected by this issue or deployment attempt.

maxLength
256
versionintegerRequired

Deployment version number for this admitted attempt.

minimum
1
maximum
9007199254740991
statusstringRequired

Status of this exact admitted deployment attempt.

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

Whether this exact deployment attempt is active and all required components are ready.

pendingComponentsarrayRequired

Deployment components that have not finished becoming ready.

maxItems
32
Schema details
Array itemstring
maxLength
128

Additional properties are not allowed.

triggerUrlChangesarray

Public trigger paths changed by this sync, with the affected workflow names.

maxItems
1000
Schema details
Array itemobject
2 fields
workflowNamestringRequired

Name of the workflow whose public trigger path stops serving.

maxLength
1024
pathstringRequired

Public trigger path that stops serving after this sync.

maxLength
4096

Additional properties are not allowed.

backgroundWorkIdstring

Workspace activity identifier for resource-copy progress.

maxLength
256
copyProgressobject

Completion status and counts for explicitly selected resource copies.

3 fields
statusstringRequired

Background resource-copy status.

enum
["pending","completed","failed"]
copiedintegerRequired

Number of resources copied successfully.

minimum
0
maximum
9007199254740991
failedintegerRequired

Number of resources that failed to copy.

minimum
0
maximum
9007199254740991

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",
    "name": "Customer support triage",
    "description": "Routes incoming support requests to the right team.",
    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
    "folderPath": "/Operations",
    "createdAt": "2026-05-01T09:00:00.000Z",
    "updatedAt": "2026-08-09T18:04:11.000Z",
    "blocks": [
      {
        "id": "block_start",
        "type": "starter",
        "name": "Start"
      },
      {
        "id": "block_triage",
        "type": "agent",
        "name": "Triage"
      },
      {
        "id": "block_reply",
        "type": "response",
        "name": "Reply"
      }
    ],
    "warnings": [
      "Triage: knowledgeBaseId was stripped by export; set it before running"
    ]
  }
}

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