> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terminaluse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate Tasks

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

Migrate tasks between versions within the same branch. Supports two modes:

* **Bulk migration**: Migrate all tasks from a source version (`from_version_id`)
* **Specific tasks**: Migrate specific tasks (`task_ids`)

Target can be explicit (`to_version_id`) or the latest active version (`to_latest`).


## OpenAPI

````yaml openapi.json POST /tasks/migrate
openapi: 3.1.0
info:
  title: Sb0 API
  version: 0.1.0
servers: []
security: []
paths:
  /tasks/migrate:
    post:
      tags:
        - Tasks
      summary: Migrate Tasks Between Versions
      description: >-
        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).
      operationId: tasks_migrate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MigrateTasksRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MigrateTasksResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
components:
  schemas:
    MigrateTasksRequest:
      description: Request model for migrating tasks between versions.
      properties:
        from_version_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Migrate ALL RUNNING tasks from this version
          title: From Version Id
        task_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: OR migrate specific task IDs
          title: Task Ids
        to_latest:
          default: false
          description: OR migrate to ACTIVE/DEPLOYING version on branch
          title: To Latest
          type: boolean
        to_version_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Explicit target version ID
          title: To Version Id
      title: MigrateTasksRequest
      type: object
    MigrateTasksResponse:
      description: Response model for task migration operation.
      properties:
        branch_id:
          description: Branch both versions belong to
          title: Branch Id
          type: string
        from_version_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Source version (if bulk mode)
          title: From Version Id
        tasks:
          description: Migrated tasks
          items:
            $ref: '#/components/schemas/TaskResponse'
          title: Tasks
          type: array
        to_version:
          $ref: '#/components/schemas/VersionResponse'
          description: Target version details
      required:
        - to_version
        - branch_id
        - tasks
      title: MigrateTasksResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    TaskResponse:
      description: Task response model with optional related data based on relationships
      properties:
        agents:
          anyOf:
            - items:
                $ref: '#/components/schemas/Agent'
              type: array
            - type: 'null'
          title: >-
            Agents associated with this task (only populated when 'agent' view
            is requested)
        created_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: The timestamp when the task was created
        created_version_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Version ID when task was created (immutable, for audit)
        current_version_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Current version for routing (can change on migration)
        filesystem_id:
          title: Filesystem ID for persistent filesystem storage
          type: string
        id:
          title: Unique Task ID
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Unique name of the task
        namespace_id:
          title: Namespace ID (denormalized from agent for GCS path construction)
          type: string
        params:
          additionalProperties: true
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Task parameters
        status:
          anyOf:
            - $ref: '#/components/schemas/TaskStatus'
            - type: 'null'
          title: The current status of the task
        status_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: The reason for the current task status
        task_metadata:
          additionalProperties: true
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Task metadata
        updated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: The timestamp when the task was last updated
      required:
        - id
        - filesystem_id
        - namespace_id
      title: TaskResponse
      type: object
    VersionResponse:
      description: Full version details.
      properties:
        acp_type:
          $ref: '#/components/schemas/ACPType'
          description: Type of ACP server (sync or async)
        author_email:
          description: Commit author email
          title: Author Email
          type: string
        author_name:
          description: Commit author name
          title: Author Name
          type: string
        branch_id:
          description: Parent branch ID
          title: Branch Id
          type: string
        created_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Creation timestamp
          title: Created At
        deployed_at:
          description: When this version was deployed
          format: date-time
          title: Deployed At
          type: string
        failure_diagnostics:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          description: >-
            User-facing failure diagnostics with 'title', 'description', and
            'action' fields
          title: Failure Diagnostics
        failure_reason:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Classified failure reason when status is FAILED (e.g.,
            'image_pull_failed', 'crash_loop', 'scheduling_failed')
          title: Failure Reason
        git_branch:
          description: Git branch name
          title: Git Branch
          type: string
        git_hash:
          description: Git commit hash
          title: Git Hash
          type: string
        git_message:
          default: ''
          description: Git commit message
          title: Git Message
          type: string
        id:
          description: Version ID
          title: Id
          type: string
        image_expires_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When image expires (for rollback window)
          title: Image Expires At
        image_url:
          description: Container image URL
          title: Image Url
          type: string
        is_dirty:
          default: false
          description: Whether the commit had uncommitted changes
          title: Is Dirty
          type: boolean
        last_rollback_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Timestamp when this version was last rolled back TO
          title: Last Rollback At
        replicas:
          default: 0
          description: Current pod count for this version
          title: Replicas
          type: integer
        retired_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When version was retired
          title: Retired At
        rollback_count:
          default: 0
          description: Number of rollbacks to this version
          title: Rollback Count
          type: integer
        rolled_back_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Timestamp when this version was rolled back FROM
          title: Rolled Back At
        sdk_type:
          $ref: '#/components/schemas/SDKType'
          description: SDK type for agent runtime
        source_filesystem_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Filesystem snapshot that can reopen this version in Agent Builder
          title: Source Filesystem Id
        status:
          $ref: '#/components/schemas/VersionStatus'
          description: Version lifecycle status
        updated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Last update timestamp
          title: Updated At
      required:
        - id
        - branch_id
        - git_hash
        - git_branch
        - author_name
        - author_email
        - image_url
        - status
        - deployed_at
        - sdk_type
        - acp_type
      title: VersionResponse
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    Agent:
      properties:
        agent_input_type:
          anyOf:
            - $ref: '#/components/schemas/AgentInputType'
            - type: 'null'
          description: The type of input the agent expects.
        created_at:
          description: The timestamp when the agent was created
          format: date-time
          title: Created At
          type: string
        description:
          description: The description of the action.
          title: Description
          type: string
        id:
          description: The unique identifier of the agent.
          title: Id
          type: string
        name:
          description: The agent name (unique within namespace).
          title: Name
          type: string
        namespace_id:
          description: The namespace ID this agent belongs to.
          title: Namespace Id
          type: string
        registered_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: The timestamp when the agent was last registered
          title: Registered At
        registration_metadata:
          additionalProperties: true
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: The metadata for the agent's registration.
          title: Registration Metadata
        status:
          $ref: '#/components/schemas/AgentStatus'
          default: ACTIVE
          description: >-
            Agent status. Runtime statuses (Ready/Failed/Unhealthy) now live on
            Deployment.
        status_reason:
          anyOf:
            - type: string
            - type: 'null'
          description: The reason for the status of the action.
          title: Status Reason
        updated_at:
          description: The timestamp when the agent was last updated
          format: date-time
          title: Updated At
          type: string
      required:
        - id
        - namespace_id
        - name
        - description
        - created_at
        - updated_at
      title: Agent
      type: object
    TaskStatus:
      enum:
        - IDLE
        - CANCELED
        - COMPLETED
        - FAILED
        - RUNNING
        - TERMINATED
        - TIMED_OUT
        - DELETED
      title: TaskStatus
      type: string
    ACPType:
      description: Type of ACP server.
      enum:
        - sync
        - async
      title: ACPType
      type: string
    SDKType:
      description: SDK type for agent runtime.
      enum:
        - claude_agent_sdk
        - codex_agent_sdk
      title: SDKType
      type: string
    VersionStatus:
      description: Status of a version in its lifecycle.
      enum:
        - DEPLOYING
        - ACTIVE
        - FAILED
        - UNHEALTHY
        - DRAINING
        - RETIRED
        - ROLLED_BACK
      title: VersionStatus
      type: string
    AgentInputType:
      enum:
        - text
        - json
      title: AgentInputType
      type: string
    AgentStatus:
      description: >-
        Agent status - runtime statuses (Ready/Failed/Unhealthy) now live on
        Deployment.
      enum:
        - ACTIVE
        - DELETED
      title: AgentStatus
      type: string

````