---
title: "Migrate Tasks Between Versions"
method: POST
path: "/tasks/migrate"
tags: ["Tasks"]
---

# Migrate Tasks Between Versions

`POST /tasks/migrate`

Migrate tasks between versions within the same branch. Supports two modes: bulk migration by source version (from_version_id), or migration of specific tasks (task_ids). Target can be explicit (to_version_id) or latest active version (to_latest).

## Request body

- MigrateTasksRequest — Request model for migrating tasks between versions.
  - `from_version_id` string, nullable — Migrate ALL RUNNING tasks from this version
  - `task_ids` string[], nullable — OR migrate specific task IDs
  - `to_latest` boolean — OR migrate to ACTIVE/DEPLOYING version on branch
  - `to_version_id` string, nullable — Explicit target version ID

## Response `200`

Successful Response

- MigrateTasksResponse — Response model for task migration operation.
  - `branch_id` string, required — Branch both versions belong to
  - `from_version_id` string, nullable — Source version (if bulk mode)
  - `tasks` TaskResponse[], required — Migrated tasks
    - `agents` Agent[], nullable
      - `agent_input_type` 'text' | 'json'
      - `created_at` string, date-time, required — The timestamp when the agent was created
      - `description` string, required — The description of the action.
      - `id` string, required — The unique identifier of the agent.
      - `name` string, required — The agent name (unique within namespace).
      - `namespace_id` string, required — The namespace ID this agent belongs to.
      - `registered_at` string, date-time, nullable — The timestamp when the agent was last registered
      - `registration_metadata` object, nullable — The metadata for the agent's registration.
      - `status` 'ACTIVE' | 'DELETED' — Agent status - runtime statuses (Ready/Failed/Unhealthy) now live on Deployment.
      - `status_reason` string, nullable — The reason for the status of the action.
      - `updated_at` string, date-time, required — The timestamp when the agent was last updated
    - `created_at` string, date-time, nullable
    - `created_version_id` string, nullable
    - `current_version_id` string, nullable
    - `filesystem_id` string, required
    - `id` string, required
    - `name` string, nullable
    - `namespace_id` string, required
    - `params` object, nullable
    - `status` 'IDLE' | 'CANCELED' | 'COMPLETED' | 'FAILED' | 'RUNNING' | 'TERMINATED' | 'TIMED_OUT' | 'DELETED'
    - `status_reason` string, nullable
    - `task_metadata` object, nullable
    - `updated_at` string, date-time, nullable
  - `to_version` VersionResponse, required — Full version details.
    - `acp_type` 'sync' | 'async', required — Type of ACP server.
    - `author_email` string, required — Commit author email
    - `author_name` string, required — Commit author name
    - `branch_id` string, required — Parent branch ID
    - `created_at` string, date-time, nullable — Creation timestamp
    - `deployed_at` string, date-time, required — When this version was deployed
    - `failure_diagnostics` object, nullable — User-facing failure diagnostics with 'title', 'description', and 'action' fields
    - `failure_reason` string, nullable — Classified failure reason when status is FAILED (e.g., 'image_pull_failed', 'crash_loop', 'scheduling_failed')
    - `git_branch` string, required — Git branch name
    - `git_hash` string, required — Git commit hash
    - `git_message` string — Git commit message
    - `id` string, required — Version ID
    - `image_expires_at` string, date-time, nullable — When image expires (for rollback window)
    - `image_url` string, required — Container image URL
    - `is_dirty` boolean — Whether the commit had uncommitted changes
    - `last_rollback_at` string, date-time, nullable — Timestamp when this version was last rolled back TO
    - `replicas` integer — Current pod count for this version
    - `retired_at` string, date-time, nullable — When version was retired
    - `rollback_count` integer — Number of rollbacks to this version
    - `rolled_back_at` string, date-time, nullable — Timestamp when this version was rolled back FROM
    - `sdk_type` 'claude_agent_sdk' | 'codex_agent_sdk', required — SDK type for agent runtime.
    - `source_filesystem_id` string, nullable — Filesystem snapshot that can reopen this version in Agent Builder
    - `status` 'DEPLOYING' | 'ACTIVE' | 'FAILED' | 'UNHEALTHY' | 'DRAINING' | 'RETIRED' | 'ROLLED_BACK', required — Status of a version in its lifecycle.
    - `updated_at` string, date-time, nullable — Last update timestamp

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/terminaluse/apis/sb0-api.md) · [All operations](https://skmtc.net/terminaluse/apis/sb0-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/terminaluse/sb0-api/revisions/f24a474dc415/schema)