---
title: "Create Migration"
method: POST
path: "/v1/namespaces/migrations/"
tags: ["Namespace Migrations"]
---

# Create Migration

`POST /v1/namespaces/migrations/`

Create a new namespace migration.

This endpoint creates a migration and optionally validates it.
Use start_immediately=True to begin execution immediately.

Args:
    request: FastAPI request
    create_request: Migration configuration

Returns:
    CreateMigrationResponse with migration ID and status

## Request body

- CreateMigrationRequest — Request to create a new migration.
  - `config` MigrationConfig, required — Configuration for a namespace migration.
    - `migration_type` 're_extract' | 'copy' | 'extend', required — Types of namespace migrations.
    - `source_namespace_id` string, required — Source namespace ID
    - `target_namespace_id` string, nullable — Target namespace ID (auto-generated if not provided)
    - `target_namespace_name` string, nullable — Name for target namespace
    - `feature_extractors` SharedNamespacesMigrationsModelsFeatureExtractorConfig[], nullable — New extractors to use (RE_EXTRACT only)
      - `feature_extractor_name` string, required — Name of the extractor
      - `version` string, nullable — Version to use
      - `parameters` object, nullable — Extractor parameters
    - `filters` ResourceFilter — Filters for selective resource migration.
      - `collection_ids` string[], nullable — Specific collection IDs to migrate
      - `taxonomy_ids` string[], nullable — Specific taxonomy IDs to migrate
      - `cluster_ids` string[], nullable — Specific cluster IDs to migrate
      - `retriever_ids` string[], nullable — Specific retriever IDs to migrate
      - `date_range` object, nullable — Date range filter (after, before)
      - `auto_include_dependencies` boolean — Automatically include required dependencies
    - `batch_options` BatchOptions — Options for batch processing in migration.
      - `batch_size` integer — Documents per batch
      - `max_workers` integer — Maximum parallel workers
      - `retry_failed` boolean — Retry failed batches
    - `taxonomy_options` TaxonomyOptions — Options for taxonomy migration.
      - `preserve_taxonomy_ids` boolean — Keep same taxonomy IDs in target
      - `preserve_enrichment_fields` boolean — Keep _taxonomy_* fields in documents
      - `re_run_enrichment` boolean — Re-run taxonomy enrichment after migration
      - `migrate_reference_collections` boolean — Automatically migrate reference collections
    - `cluster_options` ClusterOptions — Options for cluster migration.
      - `preserve_cluster_ids` boolean — Keep same cluster IDs in target
      - `preserve_assignments` boolean — Keep cluster_id in documents
      - `migrate_artifacts` boolean — Copy parquet artifacts from S3
      - `preserve_centroids` boolean — Keep centroid collections
      - `recompute_clusters` boolean — Recompute clusters instead of copying
    - `retriever_options` RetrieverOptions — Options for retriever migration.
      - `preserve_retriever_ids` boolean — Keep same retriever IDs (avoid conflicts)
      - `migrate_interactions` boolean — Migrate user interaction data
      - `migrate_execution_history` boolean — Migrate past execution history
      - `validate_references` boolean — Pre-flight check all references exist
    - `preserve_resource_ids` boolean — Preserve original resource IDs in target
    - `dry_run` boolean — Validate only, don't execute
    - `webhook_url` string, nullable — Webhook URL for status notifications
  - `start_immediately` boolean — Start execution immediately after validation

## Response `201`

Successful Response

- CreateMigrationResponse — Response after creating a migration.
  - `migration_id` string, required — Created migration ID
  - `status` 'draft' | 'validating' | 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled', required — Migration execution status.
  - `validation_result` ValidationResult — Result of pre-flight validation.
    - `valid` boolean, required — Whether migration can proceed
    - `errors` ValidationError[] — Validation errors
      - `loc` union[], required
        - union
          - string
          - integer
      - `msg` string, required
      - `type` string, required
      - `input` unknown
      - `ctx` object
    - `warnings` ValidationError[] — Validation warnings
      - `loc` union[], required
        - union
          - string
          - integer
      - `msg` string, required
      - `type` string, required
      - `input` unknown
      - `ctx` object
    - `estimated_resources` object — Estimated resource counts
    - `estimated_duration_seconds` integer, nullable — Estimated migration duration
  - `created_at` string, date-time, required — Creation timestamp
  - `message` string, required — Human-readable message

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/5d4c905106b4/schema)