---
title: "Create Sync Operation"
method: POST
path: "/workspaces/{workspace_id}/workflows/sync/operations"
tags: ["workflows"]
---

# Create Sync Operation

`POST /workspaces/{workspace_id}/workflows/sync/operations`

## Request

- Base URL: `https://platform.tracecat.com/api`
- URL: `https://platform.tracecat.com/api/workspaces/{workspace_id}/workflows/sync/operations`
- Auth: one of:
  - API key in cookie `fastapiusersauth`
  - HTTP bearer

Accept a preview and return before any Git or resource work begins.

## Path parameters

- `workspace_id` string, uuid, required

## Request body

- SyncOperationCreateInput: Start a preview; reuse the client-generated ID after a lost response.
  - `id` string, uuid, required
  - `direction` 'push' | 'pull', required
  - `push` WorkspaceSyncExportRequestInput: Request to commit selected workspace resources to a Git branch.
    - `message` string, required: Commit message for the export.
    - `branch` string, required: Target branch to commit to.
    - `create_pr` boolean: Whether to open a pull request for the commit.
    - `pr_base_branch` string, nullable: Base branch for the pull request, if created.
    - `resources` ResourceRef[], nullable: Specific resources to export, or ``None`` to export all.
      - `resource_type` 'workflow' | 'agent_preset' | 'skill' | 'table' | 'case_tag' | 'case_field' | 'case_dropdown' | 'case_duration' | 'variable' | 'secret_metadata', required: Kind of workspace resource that can be synced to and from Git. Every member is adapter-backed: it can be projected to and imported from repository files.
      - `source_id` string, nullable: Git source id of the resource, if referenced by source id.
      - `local_id` string, uuid, nullable: Local database id of the resource, if referenced by local id.
    - `include_schedules` boolean: Whether to include workflow schedules in the export.
    - `package_include` string[], nullable: Include file patterns to write with a managed resources package export. Only valid for the package source workspace; ``None`` keeps the include file already in the repository.
  - `pull` WorkflowSyncPullRequest: Request model for pulling workflows from a Git repository.
    - `commit_sha` string, required: Specific commit SHA to pull from
    - `dry_run` boolean: Validate only, don't perform actual import
    - `sync_schedules` boolean: Apply schedule definitions from Git. Defaults off to preserve destination schedules.
    - `catalog_mappings` CatalogMappingSelection[]: Explicit source-to-target model choices from the pull preview.
      - `source_catalog_id` string, uuid, required
      - `target_catalog_id` string, uuid, required
    - `mcp_integration_mappings` McpIntegrationMappingSelection[]: Explicit source-to-target MCP integration choices from the pull preview.
      - `source_mcp_integration_id` string, uuid, required
      - `target_mcp_integration_id` string, uuid, required
    - `secret_store_mappings` SecretStoreMappingSelection[]: Target stores for AWS-backed secrets whose store name has no match.
      - `source_store` string, required
      - `target_store_id` string, uuid, nullable, required
  - `compare_ref` string, nullable

## Response `202`

Successful Response

- SyncOperationRead: Small polling response, independent of the number of synced files.
  - `id` string, uuid, required
  - `direction` 'push' | 'pull', required
  - `status` 'queued' | 'running' | 'ready' | 'applying' | 'completed' | 'failed' | 'expired', required
  - `stage` 'fetching' | 'preparing' | 'awaiting_confirmation' | 'applying' | 'finishing' | 'finished', required
  - `created_at` string, date-time, required
  - `expires_at` string, date-time, required
  - `commit_sha` string, nullable
  - `error` string, nullable
  - `preview` union
    - WorkspaceSyncExportPreview: Projection summary of the resources an export would commit. Mirrors the pull dry-run preview: it projects the selected resources locally without writing to Git or mutating sync mappings.
      - `resource_counts` object, required: Count of resources to commit, keyed by resource type.
      - `files` string[], required: Repository-relative paths the export would write.
      - `resources` WorkspaceSyncPreviewResource[]: Displayable resources included in the export preview.
        - `resource_type` 'workflow' | 'agent_preset' | 'skill' | 'table' | 'case_tag' | 'case_field' | 'case_dropdown' | 'case_duration' | 'variable' | 'secret_metadata', required: Kind of workspace resource that can be synced to and from Git. Every member is adapter-backed: it can be projected to and imported from repository files.
        - `source_id` string, required: Stable Git source id for the resource.
        - `name` string, required: Human-readable resource name.
        - `path` string, required: Primary repository path written for the resource.
      - `resource_diffs` PullResourceDiff[]: Per-resource file diffs between the comparison ref and projected export.
        - `resource_type` string, required
        - `source_id` string, required
        - `source_path` string, required
        - `change_type` 'added' | 'modified' | 'deleted', required
        - `title` string, nullable, required
        - `diff` string, required
        - `truncated` boolean
    - PullResult
      - `success` boolean, required
      - `commit_sha` string, required
      - `workflows_found` integer, required
      - `workflows_imported` integer, required
      - `diagnostics` PullDiagnostic[], required
        - `workflow_path` string, required
        - `workflow_title` string, nullable, required
        - `error_type` 'conflict' | 'validation' | 'dependency' | 'parse' | 'github' | 'system' | 'transaction', required
        - `message` string, required
        - `details` object, required
      - `message` string, required
      - `resource_counts` object, nullable
      - `resource_diffs` PullResourceDiff[], nullable
        - `resource_type` string, required
        - `source_id` string, required
        - `source_path` string, required
        - `change_type` 'added' | 'modified' | 'deleted', required
        - `title` string, nullable, required
        - `diff` string, required
        - `truncated` boolean
      - `files` string[], nullable
      - `resources` SyncPreviewResource[], nullable
        - `resource_type` string, required
        - `source_id` string, required
        - `name` string, required
        - `path` string, required
      - `library_skill_installs` string[]
      - `skipped_managed` string[]
      - `catalog_mapping_requirements` CatalogMappingRequirement[], nullable
        - `source_catalog_id` string, uuid, required
        - `model_provider` string, required
        - `model_name` string, required
        - `reason` 'ambiguous' | 'invalid_selection', required
        - `message` string, required
        - `candidates` CatalogMappingCandidate[], required
          - `catalog_id` string, uuid, required
          - `model_provider` string, required
          - `model_name` string, required
          - `provider_name` string, required
          - `model_display_name` string, nullable, required
          - `endpoint_hostname` string, nullable, required
          - `origin` 'platform' | 'organization' | 'custom_provider', required
        - `affected_presets` CatalogMappingAffectedPreset[], required
          - `preset_slug` string, required
          - `preset_name` string, required
          - `version` integer, nullable, required
          - `path` string, required
        - `affected_workflows` CatalogMappingAffectedWorkflow[], required
          - `workflow_source_id` string, required
          - `workflow_path` string, required
          - `workflow_title` string, required
          - `action_ref` string, required
      - `mcp_integration_mapping_requirements` McpIntegrationMappingRequirement[], nullable
        - `source_mcp_integration_id` string, uuid, required
        - `slug` string, nullable, required
        - `name` string, nullable, required
        - `server_type` string, nullable, required
        - `auth_type` string, nullable, required
        - `reason` 'unresolved' | 'invalid_selection' | 'conflicting_metadata', required
        - `message` string, required
        - `candidates` McpIntegrationMappingCandidate[], required
          - `mcp_integration_id` string, uuid, required
          - `slug` string, required
          - `name` string, required
          - `server_type` string, required
          - `auth_type` string, required
        - `affected_presets` McpIntegrationMappingAffectedPreset[], required
          - `preset_slug` string, required
          - `preset_name` string, required
          - `version` integer, nullable, required
          - `path` string, required
        - `affected_workflows` McpIntegrationMappingAffectedWorkflow[], required
          - `workflow_source_id` string, required
          - `workflow_path` string, required
          - `workflow_title` string, required
          - `action_ref` string, required
      - `secret_store_mapping_requirements` SecretStoreMappingRequirement[], nullable
        - `source_store` string, required
        - `reason` 'unresolved' | 'invalid_selection', required
        - `message` string, required
        - `candidates` SecretStoreMappingCandidate[], required
          - `store_id` string, uuid, required
          - `name` string, required
          - `region` string, nullable, required
        - `affected_secrets` SecretStoreMappingAffectedSecret[], required
          - `secret_name` string, required
          - `environment` string, required
          - `path` string, required
  - `result` union
    - SyncPushResult: Compact durable push receipt; file details stay in paginated artifacts.
      - `commit` CommitInfo, required
        - `status` 'committed' | 'no_op', required: Status of a push/commit operation.
        - `sha` string, nullable, required
        - `ref` string, required
        - `base_ref` string, required
        - `pr_url` string, nullable
        - `pr_number` integer, nullable
        - `pr_reused` boolean
        - `message` string
    - PullResult
      - `success` boolean, required
      - `commit_sha` string, required
      - `workflows_found` integer, required
      - `workflows_imported` integer, required
      - `diagnostics` PullDiagnostic[], required
        - `workflow_path` string, required
        - `workflow_title` string, nullable, required
        - `error_type` 'conflict' | 'validation' | 'dependency' | 'parse' | 'github' | 'system' | 'transaction', required
        - `message` string, required
        - `details` object, required
      - `message` string, required
      - `resource_counts` object, nullable
      - `resource_diffs` PullResourceDiff[], nullable
        - `resource_type` string, required
        - `source_id` string, required
        - `source_path` string, required
        - `change_type` 'added' | 'modified' | 'deleted', required
        - `title` string, nullable, required
        - `diff` string, required
        - `truncated` boolean
      - `files` string[], nullable
      - `resources` SyncPreviewResource[], nullable
        - `resource_type` string, required
        - `source_id` string, required
        - `name` string, required
        - `path` string, required
      - `library_skill_installs` string[]
      - `skipped_managed` string[]
      - `catalog_mapping_requirements` CatalogMappingRequirement[], nullable
        - `source_catalog_id` string, uuid, required
        - `model_provider` string, required
        - `model_name` string, required
        - `reason` 'ambiguous' | 'invalid_selection', required
        - `message` string, required
        - `candidates` CatalogMappingCandidate[], required
          - `catalog_id` string, uuid, required
          - `model_provider` string, required
          - `model_name` string, required
          - `provider_name` string, required
          - `model_display_name` string, nullable, required
          - `endpoint_hostname` string, nullable, required
          - `origin` 'platform' | 'organization' | 'custom_provider', required
        - `affected_presets` CatalogMappingAffectedPreset[], required
          - `preset_slug` string, required
          - `preset_name` string, required
          - `version` integer, nullable, required
          - `path` string, required
        - `affected_workflows` CatalogMappingAffectedWorkflow[], required
          - `workflow_source_id` string, required
          - `workflow_path` string, required
          - `workflow_title` string, required
          - `action_ref` string, required
      - `mcp_integration_mapping_requirements` McpIntegrationMappingRequirement[], nullable
        - `source_mcp_integration_id` string, uuid, required
        - `slug` string, nullable, required
        - `name` string, nullable, required
        - `server_type` string, nullable, required
        - `auth_type` string, nullable, required
        - `reason` 'unresolved' | 'invalid_selection' | 'conflicting_metadata', required
        - `message` string, required
        - `candidates` McpIntegrationMappingCandidate[], required
          - `mcp_integration_id` string, uuid, required
          - `slug` string, required
          - `name` string, required
          - `server_type` string, required
          - `auth_type` string, required
        - `affected_presets` McpIntegrationMappingAffectedPreset[], required
          - `preset_slug` string, required
          - `preset_name` string, required
          - `version` integer, nullable, required
          - `path` string, required
        - `affected_workflows` McpIntegrationMappingAffectedWorkflow[], required
          - `workflow_source_id` string, required
          - `workflow_path` string, required
          - `workflow_title` string, required
          - `action_ref` string, required
      - `secret_store_mapping_requirements` SecretStoreMappingRequirement[], nullable
        - `source_store` string, required
        - `reason` 'unresolved' | 'invalid_selection', required
        - `message` string, required
        - `candidates` SecretStoreMappingCandidate[], required
          - `store_id` string, uuid, required
          - `name` string, required
          - `region` string, nullable, required
        - `affected_secrets` SecretStoreMappingAffectedSecret[], required
          - `secret_name` string, required
          - `environment` string, required
          - `path` string, required
  - `diff_count` integer
  - `can_retry` boolean
  - `data_applied` boolean
  - `inputs` SyncOperationCreateOutput, required: Start a preview; reuse the client-generated ID after a lost response.
    - `id` string, uuid, required
    - `direction` 'push' | 'pull', required
    - `push` WorkspaceSyncExportRequestOutput: Request to commit selected workspace resources to a Git branch.
      - `message` string, required: Commit message for the export.
      - `branch` string, required: Target branch to commit to.
      - `create_pr` boolean: Whether to open a pull request for the commit.
      - `pr_base_branch` string, nullable: Base branch for the pull request, if created.
      - `resources` ResourceRef[], nullable: Specific resources to export, or ``None`` to export all.
        - `resource_type` 'workflow' | 'agent_preset' | 'skill' | 'table' | 'case_tag' | 'case_field' | 'case_dropdown' | 'case_duration' | 'variable' | 'secret_metadata', required: Kind of workspace resource that can be synced to and from Git. Every member is adapter-backed: it can be projected to and imported from repository files.
        - `source_id` string, nullable: Git source id of the resource, if referenced by source id.
        - `local_id` string, uuid, nullable: Local database id of the resource, if referenced by local id.
      - `include_schedules` boolean: Whether to include workflow schedules in the export.
      - `package_include` string[], nullable: Include file patterns to write with a managed resources package export. Only valid for the package source workspace; ``None`` keeps the include file already in the repository.
    - `pull` WorkflowSyncPullRequest: Request model for pulling workflows from a Git repository.
      - `commit_sha` string, required: Specific commit SHA to pull from
      - `dry_run` boolean: Validate only, don't perform actual import
      - `sync_schedules` boolean: Apply schedule definitions from Git. Defaults off to preserve destination schedules.
      - `catalog_mappings` CatalogMappingSelection[]: Explicit source-to-target model choices from the pull preview.
        - `source_catalog_id` string, uuid, required
        - `target_catalog_id` string, uuid, required
      - `mcp_integration_mappings` McpIntegrationMappingSelection[]: Explicit source-to-target MCP integration choices from the pull preview.
        - `source_mcp_integration_id` string, uuid, required
        - `target_mcp_integration_id` string, uuid, required
      - `secret_store_mappings` SecretStoreMappingSelection[]: Target stores for AWS-backed secrets whose store name has no match.
        - `source_store` string, required
        - `target_store_id` string, uuid, nullable, required
    - `compare_ref` string, nullable
  - `preview_revision` integer
  - `state_revision` integer

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `422`: Validation Error
- `503`: Service Unavailable

---

[API](https://skmtc.dev/tracecat/apis/tracecat-api.md) - [All operations](https://skmtc.dev/tracecat/apis/tracecat-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tracecat/apis/tracecat-api/revisions/2efdda25045f?raw)