---
title: "Pull Workflows"
method: POST
path: "/workspaces/{workspace_id}/workflows/sync/pull"
tags: ["workflows"]
---

# Pull Workflows

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

## Request

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

Pull workflows from Git repository at specific commit.

Imports workflow definitions from the specified repository and commit,
with configurable conflict resolution strategy. Repository URL is retrieved
from workspace settings.

## Path parameters

- `workspace_id` string, uuid, required

## Request body

- 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

## Response `200`

Successful Response

- 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

## Other responses

- `422`: Validation Error

---

[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)