Workspace sync

Push workspace

Apply a reviewed sync from this workspace into the other workspace along a direct fork edge. Requires Admin access to both workspaces. Creates unmatched deployed workflows, overwrites mapped target drafts, and archives mapped targets whose sources were deleted or archived. Undeployed sources alone do not archive targets. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Send `confirm: true`, the fingerprint from a preview with identical choices, and a stable request ID. The example hash is illustrative. Changed or unresolved plans return `409` without applying. Identical retries return the committed operation; changed inputs with that ID return `409`. Copies and deployment activation can finish after the transaction commits. Poll Get workspace operation before treating the target as ready. 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

Send confirm: true, the fingerprint from a preview with identical choices, and a stable request ID. The example hash is illustrative. Changed or unresolved plans return 409 without applying. Identical retries return the committed operation; changed inputs with that ID return 409. Copies and deployment activation can finish after the transaction commits. Poll Get workspace operation before treating the target as ready. 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

Confirmed current-to-other choices, actual preview fingerprint, and stable request ID.

@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

Confirmed current-to-other choices, actual preview fingerprint, and stable request ID.

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

requestIdstringRequired

Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation.

minLength: 1
maxLength: 128

previewFingerprintstringRequired

Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value.

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

confirmbooleanRequired

Confirm replacement of mapped target drafts and archival of mapped targets whose sources were deleted or archived.

const: true

Additional properties are not allowed.

Request example 1

json

{
  "otherWorkspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
  "requestId": "push-support-2026-10-13",
  "previewFingerprint": "c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a",
  "confirm": true
}

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

Committed push receipt with copy and deployment readiness.

@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

Committed push receipt with copy and deployment readiness.

1 field

dataobjectRequired

Response data.

14 fields

operationIdstringRequired

Durable operation identifier to use for polling.

minLength: 1
maxLength: 256

requestIdstringRequired

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

minLength: 1
maxLength: 128

workspaceIdstringRequired

Explicit current workspace scope.

minLength: 1
maxLength: 128

kindstringRequired

Type of committed workspace operation.

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

appliedbooleanRequired

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

const: true

statusstringRequired

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

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

resourceIdsarrayRequired

Identifiers of resources created or changed by the committed operation.

maxItems: 5000

Schema details

Array itemstring

minLength: 1
maxLength: 256

issuesarrayRequired

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.

Response example 1

json

{
  "data": {
    "operationId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
    "requestId": "push-support-2026-10-13",
    "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
    "kind": "workspace_push",
    "applied": true,
    "status": "processing",
    "resourceIds": [
      "destination_workflow_id"
    ],
    "issues": []
  }
}

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' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "otherWorkspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
  "requestId": "push-support-2026-10-13",
  "previewFingerprint": "c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a",
  "confirm": true
}'

const response = await fetch("https://www.sim.ai/api/v2/workspaces/string/fork/push", {
  "method": "POST",
  "headers": {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "body": "{\n  \"otherWorkspaceId\": \"9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94\",\n  \"requestId\": \"push-support-2026-10-13\",\n  \"previewFingerprint\": \"c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a\",\n  \"confirm\": true\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",
    headers={
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json"
},
    data="{\n  \"otherWorkspaceId\": \"9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94\",\n  \"requestId\": \"push-support-2026-10-13\",\n  \"previewFingerprint\": \"c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a\",\n  \"confirm\": true\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", strings.NewReader("{\n  \"otherWorkspaceId\": \"9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94\",\n  \"requestId\": \"push-support-2026-10-13\",\n  \"previewFingerprint\": \"c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a\",\n  \"confirm\": true\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"));
    builder.header("X-API-Key", "YOUR_API_KEY");
    builder.header("Content-Type", "application/json");
    var request = builder.method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"otherWorkspaceId\": \"9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94\",\n  \"requestId\": \"push-support-2026-10-13\",\n  \"previewFingerprint\": \"c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a\",\n  \"confirm\": true\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");
request.Content = new StringContent("{\n  \"otherWorkspaceId\": \"9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94\",\n  \"requestId\": \"push-support-2026-10-13\",\n  \"previewFingerprint\": \"c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a\",\n  \"confirm\": true\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": {
    "operationId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
    "requestId": "push-support-2026-10-13",
    "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
    "kind": "workspace_push",
    "applied": true,
    "status": "processing",
    "resourceIds": [
      "destination_workflow_id"
    ],
    "issues": []
  }
}

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

Request example 1

Responses

200

Response example 1

400

401

403

404

409

413

429

Response headers

500

503

Response headers