Workspace sync

Preview workflow import

Validate destination mappings and configuration with workspace write access, without creating a workflow. The result reports readiness, unresolved fields, discovery instructions, and a fingerprint for mapped import with the same choices. Imported provenance never authorizes or queries a source workspace. OAuth scope: `api:write`.

POST/api/v2/workflows/import/preview

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

Portable workflow data and destination metadata for an import.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Portable workflow data and destination metadata for an import.

8 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.

Request example 1

json

{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "folderPath": "/Operations",
  "workflow": {
    "blocks": {},
    "edges": []
  }
}

Responses

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

Import readiness, unresolved bindings, and destination discovery instructions.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Import readiness, unresolved bindings, and destination discovery instructions.

1 field

dataobjectRequired

Response data.

7 fields

previewFingerprintstringRequired

Fingerprint to send when applying this import with the same choices. Preview again after changing any choice.

minLength: 64
maxLength: 64

readybooleanRequired

Whether every required destination binding and configuration field is resolved for import.

bindingsarrayRequired

Resolved and unresolved source occurrences with their destination selections.

maxItems: 10000

Schema details

Array itemobject

5 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.

maxLength: 4096

targetIdvalueRequired

Authorized destination identifier, or null to clear the mapping.

Schema details

Any of

Option 1string

maxLength: 4096

Option 2null

requiredbooleanRequired

Whether the reference or configuration is required for this operation.

occurrenceobjectRequired

Registered source field occurrence addressed by this binding.

5 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

valuePatharrayRequired

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

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

encodingstringRequired

Registered encoding used to discover and rewrite the reference.

enum: ["scalar","array","csv","files","environment"]

Additional properties are not allowed.

unresolvedBindingsarrayRequired

Source references that still require destination mappings or explicit copy choices.

maxItems: 10000

Schema details

Array itemobject

5 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.

maxLength: 4096

targetIdvalueRequired

Authorized destination identifier, or null to clear the mapping.

Schema details

Any of

Option 1string

maxLength: 4096

Option 2null

requiredbooleanRequired

Whether the reference or configuration is required for this operation.

occurrenceobjectRequired

Registered source field occurrence addressed by this binding.

5 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

valuePatharrayRequired

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

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

encodingstringRequired

Registered encoding used to discover and rewrite the reference.

enum: ["scalar","array","csv","files","environment"]

Additional properties are not allowed.

configurationarrayRequired

Dependent fields that may need destination-specific values.

maxItems: 10000

Schema details

Array itemobject

9 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: 1024

titlestringRequired

Human-readable configuration field label.

maxLength: 1024

requiredbooleanRequired

Whether the reference or configuration is required for this operation.

configuredbooleanRequired

Whether this destination field currently has a nonempty value.

multiSelectboolean

Whether the field accepts comma-separated selections.

selectorKeystring

Registered selector key for discovering this field’s destination options.

maxLength: 256

contextobjectRequired

Allowlisted selector dependencies scoped to the destination workspace.

Schema details

Additional propertiesstring

maxLength: 16384

requiresAuthenticationbooleanRequired

Whether a human must connect the provider before choices can be discovered.

Additional properties are not allowed.

unresolvedConfigurationarrayRequired

Required destination configuration that remains empty.

maxItems: 10000

Schema details

Array itemobject

9 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: 1024

titlestringRequired

Human-readable configuration field label.

maxLength: 1024

requiredbooleanRequired

Whether the reference or configuration is required for this operation.

configuredbooleanRequired

Whether this destination field currently has a nonempty value.

multiSelectboolean

Whether the field accepts comma-separated selections.

selectorKeystring

Registered selector key for discovering this field’s destination options.

maxLength: 256

contextobjectRequired

Allowlisted selector dependencies scoped to the destination workspace.

Schema details

Additional propertiesstring

maxLength: 16384

requiresAuthenticationbooleanRequired

Whether a human must connect the provider before choices can be discovered.

Additional properties are not allowed.

discoveryarrayRequired

CLI operations for discovering suitable destination resources.

maxItems: 32

Schema details

Array itemobject

3 fields

kindstringRequired

Resource or operation kind.

maxLength: 256

commandstringRequired

CLI command to enumerate destination candidates.

maxLength: 1024

humanAuthorizationMayBeRequiredbooleanRequired

Whether discovery may require a human OAuth authorization step.

Additional properties are not allowed.

The request is invalid. This includes a query parameter sent with no value (?limit=, ?search=), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

enum: ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}

The API credential is missing or invalid.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

enum: ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

The caller lacks the rights this operation requires. When the cause is one a caller can act on, error.details.code names it. A resource in a workspace the caller cannot reach at all answers 404 instead, so absence and denial are indistinguishable.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

enum: ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}

The requested resource was not found.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

enum: ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}

The request conflicts with current resource state.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

enum: ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "CONFLICT",
    "message": "The request conflicts with current resource state"
  }
}

The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

enum: ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  }
}

The caller exceeded the request rate limit.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

enum: ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}

Response headers

Retry-Afterinteger

Seconds to wait before retrying, sent on 429 and 503. Add jitter rather than retrying at exactly this offset.

minimum: 0
maximum: 9007199254740991

An unexpected server error occurred.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

enum: ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

A required service is temporarily unavailable. When present, Retry-After gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

enum: ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}

Response headers

Retry-Afterinteger

Seconds to wait before retrying, sent on 429 and 503. Add jitter rather than retrying at exactly this offset.

minimum: 0
maximum: 9007199254740991

Suggest an edit

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

Request

curl --request POST 'https://www.sim.ai/api/v2/workflows/import/preview' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "folderPath": "/Operations",
  "workflow": {
    "blocks": {},
    "edges": []
  }
}'

const response = await fetch("https://www.sim.ai/api/v2/workflows/import/preview", {
  "method": "POST",
  "headers": {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "body": "{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"folderPath\": \"/Operations\",\n  \"workflow\": {\n    \"blocks\": {},\n    \"edges\": []\n  }\n}"
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();

import requests

response = requests.request(
    "POST",
    "https://www.sim.ai/api/v2/workflows/import/preview",
    headers={
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json"
},
    data="{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"folderPath\": \"/Operations\",\n  \"workflow\": {\n    \"blocks\": {},\n    \"edges\": []\n  }\n}",
)
response.raise_for_status()
result = response.json()

package main

import (
  "io"
  "net/http"
  "os"
  "strings"
)

func check(err error) {
  if err != nil { panic(err) }
}

func must[T any](value T, err error) T {
  check(err)
  return value
}

func main() {

  request := must(http.NewRequest("POST", "https://www.sim.ai/api/v2/workflows/import/preview", strings.NewReader("{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"folderPath\": \"/Operations\",\n  \"workflow\": {\n    \"blocks\": {},\n    \"edges\": []\n  }\n}")))
  request.Header.Set("X-API-Key", "YOUR_API_KEY")
  request.Header.Set("Content-Type", "application/json")
  response := must(http.DefaultClient.Do(request))
  defer response.Body.Close()
  if response.StatusCode >= 400 { panic(response.Status) }
  must(io.Copy(os.Stdout, response.Body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    var builder = HttpRequest.newBuilder(URI.create("https://www.sim.ai/api/v2/workflows/import/preview"));
    builder.header("X-API-Key", "YOUR_API_KEY");
    builder.header("Content-Type", "application/json");
    var request = builder.method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"folderPath\": \"/Operations\",\n  \"workflow\": {\n    \"blocks\": {},\n    \"edges\": []\n  }\n}")).build();
    var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofInputStream());
    try (var body = response.body()) {
      if (response.statusCode() >= 400) throw new IllegalStateException("HTTP " + response.statusCode());
      body.transferTo(System.out);
    }
  }
}

using System;
using System.IO;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.sim.ai/api/v2/workflows/import/preview");
request.Content = new StringContent("{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"folderPath\": \"/Operations\",\n  \"workflow\": {\n    \"blocks\": {},\n    \"edges\": []\n  }\n}", Encoding.UTF8);
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY");
request.Content!.Headers.ContentType = System.Net.Http.Headers.MediaTypeHeaderValue.Parse("application/json");
using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
response.EnsureSuccessStatusCode();
await response.Content.CopyToAsync(Console.OpenStandardOutput());

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

Response

{
  "data": {
    "previewFingerprint": "string",
    "ready": true,
    "bindings": [
      {
        "kind": "credential",
        "sourceId": "string",
        "targetId": "string",
        "required": true,
        "occurrence": {
          "blockId": "string",
          "subBlockKey": "string",
          "valuePath": [
            "string"
          ],
          "encoding": "scalar"
        }
      }
    ],
    "unresolvedBindings": [
      {
        "kind": "credential",
        "sourceId": "string",
        "targetId": "string",
        "required": true,
        "occurrence": {
          "blockId": "string",
          "subBlockKey": "string",
          "valuePath": [
            "string"
          ],
          "encoding": "scalar"
        }
      }
    ],
    "configuration": [
      {
        "blockId": "string",
        "subBlockKey": "string",
        "title": "string",
        "required": true,
        "configured": true,
        "context": {},
        "requiresAuthentication": true
      }
    ],
    "unresolvedConfiguration": [
      {
        "blockId": "string",
        "subBlockKey": "string",
        "title": "string",
        "required": true,
        "configured": true,
        "context": {},
        "requiresAuthentication": true
      }
    ],
    "discovery": [
      {
        "kind": "string",
        "command": "string",
        "humanAuthorizationMayBeRequired": true
      }
    ]
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}

OpenAPI document ↗Download the specification

Authentication

Request body

Request example 1

Responses

200

400

401

403

404

409

413

429

Response headers

500

503

Response headers