Skip to content

API guides

Workflow imports and workspace sync

Preview destination choices, apply imports or workspace sync, and reconcile their operations.

Import an exported workflow as a draft, or fork and synchronize workspaces through the v2 preview-and-apply protocol. Preview the destination bindings, apply those exact choices, then poll the returned operation to verify copies and deployment readiness. The CLI workflow guide uses the same protocol.

Choose the interface

HTTP paths below are relative to /api/v2. {workspaceId} is the current workspace you explicitly selected.

CLI commandHTTP request
sim workflows export <id> --include-referencesGET /workflows/{workflowId}/export?includeReferences=true
sim workflows import-preview / sim workflows importPOST /workflows/import/preview / POST /workflows/import
sim workspaces fork-availability / sim workspaces lineageGET /workspaces/{workspaceId}/fork/availability / .../fork/lineage
sim workspaces children / sim workspaces fork-resourcesGET /workspaces/{workspaceId}/fork/children / .../fork/resources?kind=tables
sim workspaces fork-preview / sim workspaces forkPOST /workspaces/{workspaceId}/fork/preview / .../fork
sim workspaces push-preview / sim workspaces push --yesPOST /workspaces/{workspaceId}/fork/push/preview / .../fork/push
sim workspaces pull-preview / sim workspaces pull --yesPOST /workspaces/{workspaceId}/fork/pull/preview / .../fork/pull
sim workspaces mappings get / sim workspaces mappings updateGET / PUT /workspaces/{workspaceId}/fork/mappings
sim selectors list / sim selectors getPOST /selectors/list / POST /selectors/get
sim workspaces operations get <id> / sim workspaces operations wait <id>GET /workspaces/{workspaceId}/operations/{operationId}; wait polls this endpoint
sim workspaces operations listGET /workspaces/{workspaceId}/operations

The sync reference documents fields and includes rollback, unlink, and exclusions. Children, resource discovery, mappings, and operations are paginated: follow nextCursor with the same scope and filters.

Prerequisites and access

Set BASE_URL to your deployment origin, without /api/v2. Use a personal API key in X-API-Key, or an OAuth token in Authorization: Bearer. Examples use separate authorized source/destination keys where applicable. Replace all example resource IDs with IDs from your export and destination.

OperationRequired access
ExportWorkflow read access
Import preview/applyDestination write access; binding credentials also requires an acting user with credential access
Fork discovery, preview, creationSource workspace Admin; creation policy must allow a new workspace
Sync preview/apply and mapping read/updateAdmin on both workspaces on a direct parent/child fork edge
Rollback / unlinkTarget Admin / acting-side Admin, respectively
Selector discoveryRead access in the discovery workspace and access to the selected credential
Operation get/listRead access in the receipt workspace

Workspace keys can import where authoring policy allows, but cannot bind credentials, administer forks, or execute selectors. The key owner is not a substitute for an acting user. Workspace policies, permission groups, credential access, and workspace creation limits still apply.

OAuth import/fork/sync previews require api:write, even though previews do not commit changes. Export, fork discovery, mapping reads, selectors, and operation reads use api:read.

Forking and sync require the owning organization's Enterprise entitlement on billing-enabled deployments. On billing-disabled deployments, deployment configuration must enable forking. Check Fork availability before starting. Imports, selector discovery, and operation reports have their own access rules and do not inherit the fork-specific gate.

Import a portable workflow

Export and inspect the source

Default exports clear registered credential fields and workspace bindings. includeReferences=true adds a versioned manifest of resource IDs and their source occurrences, including nested tools. The manifest contains identities, not secret values. Unresolved environment-variable references remain, and ordinary workflow variable values or literal configuration can remain in the full export. Inspect the payload before sharing it.

Source IDs and imported provenance are labels; they do not grant access to an alleged source workspace. includeWorkspaceBindings=true can retain non-secret bindings for a same-workspace round trip; otherwise configure any required bindings reported by import.

Raw HTTP wraps the result in data; the CLI unwraps a single resource. Extract that payload before saving it:

Code