Workspace sync

Preview workspace push

Preview changes from this workspace into the other workspace along a direct fork edge. Requires Admin access to both workspaces. The plan lists workflows to create, replace, or archive; replacements overwrite target drafts with the source deployment. Proposed mappings are not saved. Dependent choices use source workflow, block, and field IDs. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:write`.

POST/api/v2/workspaces/{workspaceId}/fork/push/preview

Preview changes from this workspace into the other workspace along a direct fork edge. Requires Admin access to both workspaces. The plan lists workflows to create, replace, or archive; replacements overwrite target drafts with the source deployment. Proposed mappings are not saved. Dependent choices use source workflow, block, and field IDs. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as FORKING_ENABLED. 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

workspaceIdstringRequired

Explicit current workspace scope.

minLength: 1
maxLength: 128

Request body

Required

Other workspace and proposed source-to-target sync choices.

@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

Other workspace and proposed source-to-target sync choices.

6 fields

otherWorkspaceIdstringRequired

Workspace on the other side of the direct fork edge.

minLength: 1
maxLength: 128

mappingsarray

Proposed mapping entries addressed by resource type and sourceId. Preview does not save them; apply commits them with the sync.

maxItems: 5000

Schema details

Array itemobject

3 fields

resourceTypestringRequired

Resource type stored on the canonical parent/child edge.

enum: ["oauth_credential","service_account_credential","env_var","table","knowledge_base","file","file_folder","mcp_server","custom_block","custom_tool","skill","sandbox"]

sourceIdstringRequired

Source resource identifier in the canonical 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.

dependentValuesarray

Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them.

maxItems: 2000

Schema details

Array itemobject

4 fields

sourceWorkflowIdstringRequired

Workflow identifier in the source workspace.

minLength: 1

sourceBlockIdstringRequired

Block identifier in the source workflow.

minLength: 1
maxLength: 256

subBlockKeystringRequired

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

minLength: 1
maxLength: 1024

valuestringRequired

Destination value for the registered dependent field.

maxLength: 65536

Additional properties are not allowed.

copyResourcesobject

Explicit source resources to copy before syncing the workflows.

6 fields

knowledgeBasesarray

Source knowledge base identifiers whose documents and content are copied.

maxItems: 2000

Schema details

Array itemstring

minLength: 1

tablesarray

Source table identifiers whose schemas and rows are copied.

maxItems: 2000

Schema details

Array itemstring

minLength: 1

customToolsarray

Source custom tool identifiers to copy.

maxItems: 2000

Schema details

Array itemstring

minLength: 1

skillsarray

Source skill identifiers to copy.

maxItems: 2000

Schema details

Array itemstring

minLength: 1

filesarray

Workspace file storage keys to copy.

maxItems: 2000

Schema details

Array itemstring

minLength: 1

mcpServersarray

External MCP server identifiers to copy; OAuth connections require authorization in the destination.

maxItems: 2000

Schema details

Array itemstring

minLength: 1

Additional properties are not allowed.

dropReferencesarray

Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped.

maxItems: 2000

Schema details

Array itemobject

2 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"]

sourceIdstringRequired

Source resource identifier in the canonical source workspace.

minLength: 1
maxLength: 4096

Additional properties are not allowed.

triggerMappingsarray

Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected.

maxItems: 500

Schema details

Array itemobject

3 fields

sourceWorkflowIdstringRequired

Workflow identifier in the source workspace.

minLength: 1

sourceBlockIdstringRequired

Source trigger block identifier from the sync preview.

minLength: 1
maxLength: 256

adoptPathvalueRequired

An adoptable path offered for this trigger, or null to allocate a new path.

Schema details

Any of

Option 1string

minLength: 1
maxLength: 4096

Option 2null

Additional properties are not allowed.

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; }

Current-to-other workflow actions, required choices, and preview fingerprint.

@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

Current-to-other workflow actions, required choices, and preview fingerprint.

1 field

dataobjectRequired

Response data.

10 fields

previewFingerprintstringRequired

Fingerprint to submit when applying this preview with the same choices. Preview again after changing a choice.

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

sourceWorkspaceIdstringRequired

Canonical workspace the workflows and resources are copied from.

minLength: 1
maxLength: 128

targetWorkspaceIdstringRequired

Canonical workspace receiving the changes.

minLength: 1
maxLength: 128

readybooleanRequired

Whether required bindings, configuration, and sync blockers are resolved. This does not mean the target is already deployed.

workflowsarrayRequired

Eligible workflows and their planned actions.

maxItems: 2000

Schema details

Array itemobject

5 fields

actionstringRequired

Planned workflow creation, replacement, or archival.

enum: ["create","replace","archive"]

sourceWorkflowIdstring

Workflow identifier in the source workspace.

minLength: 1

targetWorkflowIdstring

Existing target workflow identifier; absent when apply will create a new target.

minLength: 1

namestringRequired

Display name of the workflow or workspace.

maxLength: 1024

comparisonvalue

Last successfully synced source deployment compared with the source deployment pinned by this preview. Absent for archive actions.

Schema details

Exactly one of

Option 1object

3 fields

statusstringRequired

Both exact source snapshots are available.

const: available

baseobjectRequired

Source deployment last successfully synced to this destination.

2 fields

idstringRequired

Exact source deployment snapshot identifier.

minLength: 1

versionintegerRequired

Saved version number in the source workflow.

minimum: 1
maximum: 2147483647

Additional properties are not allowed.

targetobjectRequired

Pinned source deployment that this sync would copy.

2 fields

idstringRequired

Exact source deployment snapshot identifier.

minLength: 1

versionintegerRequired

Saved version number in the source workflow.

minimum: 1
maximum: 2147483647

Additional properties are not allowed.

Option 2object

3 fields

statusstringRequired

The source baseline cannot be compared.

const: unavailable

reasonstringRequired

New destination workflow, no recorded successful sync, or deleted baseline snapshot.

enum: ["new_workflow","no_baseline","missing_baseline"]

targetobjectRequired

Pinned source deployment that this sync would copy.

2 fields

idstringRequired

Exact source deployment snapshot identifier.

minLength: 1

versionintegerRequired

Saved version number in the source workflow.

minimum: 1
maximum: 2147483647

Additional properties are not allowed.

unresolvedBindingsarrayRequired

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

maxItems: 10000

Schema details

Array itemobject

4 fields

kindstringRequired

Resource or operation kind.

maxLength: 256

sourceIdstringRequired

Source resource identifier in the canonical source workspace.

maxLength: 4096

blockNamestring

Display name of the affected source block.

maxLength: 1024

reasonstring

Structured explanation of the unresolved binding.

maxLength: 256

Additional properties are not allowed.

configurationarrayRequired

Dependent fields that may need destination-specific values.

maxItems: 10000

Schema details

Array itemobject

13 fields

sourceWorkflowIdstringRequired

Workflow identifier in the source workspace.

minLength: 1

sourceBlockIdstringRequired

Block identifier in the source workflow.

maxLength: 256

subBlockKeystringRequired

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

maxLength: 1024

titlestringRequired

Human-readable configuration field label.

maxLength: 1024

requiredbooleanRequired

Whether the reference or configuration is required for this operation.

currentValuestringRequired

Persisted sync override or proposed override; empty when neither is configured.

maxLength: 65536

multiSelectboolean

Whether the field accepts comma-separated selections.

selectorKeystring

Registered selector key for discovering this field’s options.

maxLength: 256

discoveryWorkspaceIdstringRequired

Workspace scope for selector discovery: source for a parent being copied, otherwise destination.

minLength: 1
maxLength: 128

contextobjectRequired

Allowlisted selector dependencies scoped to discoveryWorkspaceId.

Schema details

Additional propertiesstring

maxLength: 4096

parentKindstringRequired

Resource kind that owns this dependent configuration.

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

parentSourceIdstringRequired

Source identifier of the parent resource being mapped.

maxLength: 4096

parentContextKeystring

Selector context key supplied by the mapped parent resource.

maxLength: 256

Additional properties are not allowed.

excludedTargetsarrayRequired

Target workflows explicitly excluded from sync.

maxItems: 1000

Schema details

Array itemobject

2 fields

idstringRequired

Resource identifier.

minLength: 1

namestringRequired

Display name of the workflow or workspace.

maxLength: 1024

Additional properties are not allowed.

triggerSlotsarrayRequired

Source triggers and the target paths available for explicit adoption choices.

maxItems: 10000

Schema details

Array itemobject

7 fields

sourceWorkflowIdstringRequired

Workflow identifier in the source workspace.

minLength: 1

sourceBlockIdstringRequired

Stable source trigger block identifier to use in trigger mappings.

minLength: 1
maxLength: 256

blockNamestringRequired

Display name of the source trigger block.

maxLength: 1024

workflowNamestringRequired

Display name of the source workflow.

maxLength: 1024

ownPathvalueRequired

Existing target trigger path, preserved automatically and not configurable.

Schema details

Any of

Option 1string

maxLength: 4096

Option 2null

adoptablePathsarrayRequired

Retiring paths in the same target workflow with a compatible trigger provider.

maxItems: 1000

Schema details

Array itemstring

minLength: 1
maxLength: 4096

defaultAdoptPathvalueRequired

Default adoption when ownPath is null; null then allocates a new path.

Schema details

Any of

Option 1string

maxLength: 4096

Option 2null

Additional properties are not allowed.

triggerUrlChangesarrayRequired

Retiring target trigger URLs no arriving trigger adopts.

maxItems: 1000

Schema details

Array itemobject

2 fields

workflowNamestringRequired

Name of the affected workflow.

maxLength: 1024

pathstringRequired

Public trigger path that stops serving after this sync.

maxLength: 4096

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/workspaces/string/fork/push/preview' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "otherWorkspaceId": "string"
}'

const response = await fetch("https://www.sim.ai/api/v2/workspaces/string/fork/push/preview", {
  "method": "POST",
  "headers": {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "body": "{\n  \"otherWorkspaceId\": \"string\"\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/workspaces/string/fork/push/preview",
    headers={
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json"
},
    data="{\n  \"otherWorkspaceId\": \"string\"\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/workspaces/string/fork/push/preview", strings.NewReader("{\n  \"otherWorkspaceId\": \"string\"\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/workspaces/string/fork/push/preview"));
    builder.header("X-API-Key", "YOUR_API_KEY");
    builder.header("Content-Type", "application/json");
    var request = builder.method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"otherWorkspaceId\": \"string\"\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/workspaces/string/fork/push/preview");
request.Content = new StringContent("{\n  \"otherWorkspaceId\": \"string\"\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",
    "sourceWorkspaceId": "string",
    "targetWorkspaceId": "string",
    "ready": true,
    "workflows": [
      {
        "action": "create",
        "name": "string"
      }
    ],
    "unresolvedBindings": [
      {
        "kind": "string",
        "sourceId": "string"
      }
    ],
    "configuration": [
      {
        "sourceWorkflowId": "string",
        "sourceBlockId": "string",
        "subBlockKey": "string",
        "title": "string",
        "required": true,
        "currentValue": "string",
        "discoveryWorkspaceId": "string",
        "context": {},
        "parentKind": "credential",
        "parentSourceId": "string"
      }
    ],
    "excludedTargets": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "triggerSlots": [
      {
        "sourceWorkflowId": "string",
        "sourceBlockId": "string",
        "blockName": "string",
        "workflowName": "string",
        "ownPath": "string",
        "adoptablePaths": [
          "string"
        ],
        "defaultAdoptPath": "string"
      }
    ],
    "triggerUrlChanges": [
      {
        "workflowName": "string",
        "path": "string"
      }
    ]
  }
}

{
  "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

Path parameters

Request body

Responses

200

400

401

403

404

409

413

429

Response headers

500

503

Response headers