Workspace transfers API reference

This topic provides reference information about the workspace transfers API. This API lets you move a workspace from one organization to another within the same Terraform Enterprise instance.

Overview

The scope of the API includes the following endpoints:

Method	Path	Action
`POST`	`/workspace-transfers`	Call this endpoint to queue a new workspace transfer
`GET`	`/workspace-transfers`	Call this endpoint to list all workspace transfers.
`GET`	`/workspace-transfers/:transfer_id`	Call this endpoint to get the status of a workspace transfer.
`POST`	`/workspace-transfers/:transfer_id/actions/cancel`	Call this endpoint to cancel a transfer.
`POST`	`/workspace-transfers/:transfer_id/actions/resume`	Call this endpoint to resume a paused transfer.

When you transfer a workspace, Terraform Enterprise creates a new workspace in the destination organization and copies the following workspace data to the new workspace:

Run history
State history
Workspace variables
Workspace tags
Policy set connections

By default, Terraform Enterprise does not modify or remove the source workspace until you review and approve the migrated destination workspace. Once approved, Terraform Enterprise removes the source workspace and remaps the transferred workspace and related resource IDs so the destination workspace maintains its workspace ID and history.

Terraform Enterprise does not automatically recreate every configured integration. Verify the following configurations after completing the transfer:

VCS connections
SSH keys
Variable sets
Notification configuration
Run triggers
Agent pools
Run tasks
Team access

Requirements

To call the endpoints in this API, you must meet the following requirements:

You must authenticate all requests to these API endpoints with a user token.
The user token must either belong to a Terraform Enterprise administrator, or a member of the owners team in both the source and destination organization.

Transfer a workspace

Call the following endpoint to queue an operation to transfer a workspace from the source organization to the destination organization:

POST /workspace-transfers

To transfer a workspace, you must meet the following conditions:

The source and destination organization must be different.
The source workspace must not currently have a queued or active transfer.
The source workspace must not be locked.
The destination project must exist.
The destination organization must not already contain a workspace with the same desired name.

Status	Response	Reason
201	JSON API document	Successfully queued a workspace transfer.
404	JSON API error object	Not found or the user is unauthorized to perform this action.
422	JSON API error object	Malformed request body, such as missing attributes and wrong types.
500	JSON API error object	Internal system failure.

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"workspace-transfers"`.
`data.attributes.approval-mode`	string	`required`	Use `required` to pause for human approval before deleting the source workspace. Use `auto` for unattended migrations.
`data.attributes.cleanup-on-failure`	boolean	`false`	If set to `true` and the transfer fails, the workspace is deleted in the destination organization.
`data.attributes.history-cutoff`	string	`null`	Copy runs and state versions after this ISO 8601 formatted timestamp. Use `null` to copy the workspace’s entire history.
`data.attributes.policy-set-mode`	string	`attach`	Use `attach` to link policy sets by name in the destination workspace. Use `skip` to ignore policy set connections.
`data.attributes.variable-mode`	string	`copy`	Use `copy` to create workspace variable and values in the destination workspace. Vault-encrypted values are decrypted and re-encrypted automatically. Use `skip` to ignore workspace variables.
`data.attributes.workspace-prefix`	string	`null`	String to prepend to the workspace name in the destination organization.
`data.attributes.workspace-suffix`	string	`null`	String to append to the workspace name in the destination organization.
`data.relationships.source-workspace.data.id`	string		ID of the workspace to transfer.
`data.relationships.source-workspace.data.type`	string		Must be `"workspaces"`.
`data.relationships.destination-organization.data.id`	string		ID of the organization to transfer the workspace to.
`data.relationships.destination-organization.data.type`	string		Must be `"organizations"`
`data.relationships.destination-project.data.id`	string		ID of the project in the destination organization to transfer the workspace to.
`data.relationships.destination-project.data.type`	string		Must be `"projects"`

Sample payload

{ 
  "data": { 
    "type": "workspace-transfers", 
    "attributes": { 
      "approval-mode": "required", 
      "cleanup-on-failure": false, 
      "history-cutoff": "2025-01-01T00:00:00.000Z", 
      "policy-set-mode": "attach", 
      "variable-mode": "copy", 
      "workspace-prefix": null, 
      "workspace-suffix": "-imported-2026" 
    }, 
    "relationships": { 
      "source-workspace": { 
        "data": { "id": "ws-abc123XYZ", "type": "workspaces" } 
      }, 
      "destination-organization": { 
        "data": { "id": "org-destABC", "type": "organizations" } 
      }, 
      "destination-project": { 
        "data": { "id": "prj-infra456", "type": "projects" } 
      } 
    } 
  } 
}

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://tfe.example.com/api/v2/workspace-transfers

Sample response

{
  "data": {
    "id": "wt-eqrgP1sKSQJkGLBm",
    "type": "workspace-transfers",
    "attributes": {
      "status": "pending",
      "pause-reason": null,
      "approval-mode": "required",
      "cleanup-on-failure": false,
      "history-cutoff": "2025-01-01T00:00:00.000Z",
      "policy-set-mode": "attach",
      "variable-mode": "copy",
      "workspace-prefix": null,
      "workspace-suffix": "-imported-2026",
      "source-workspace-id": "ws-abc123XYZ",
      "destination-workspace-id": null,
      "source-organization-id": " org-srcABC",
      "destination-organization-id": " org-destABC",
      "destination-project-id": "prj-infra456",
      "created-at": "2026-04-06T15:50:06.623Z",
      "updated-at": "2026-04-06T15:50:06.623Z"
    },
    "relationships": {
      "events": {
        "meta": {}
      }
    }
  }
}

List all transfers

This endpoint lists all workspace transfers the authenticated user has access to.

GET /workspace-transfers

Query parameters

This endpoint accepts the following query parameters in the URL:

Parameter	Description
`include`	Use `events` to retrieve the full audit trail for the transfer. This audit trails includes information such as errors, retries, and user actions.

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://tfe.example.com/api/v2/workspace-transfers

Sample response

{
  "data": [
    {
      "id": "wt-zRuUaGwFpRiZJBbf",
      "type": "workspace-transfers",
      "attributes": {
        "status": "in_progress",
        "pause-reason": null,
        "approval-mode": "auto",
        "cleanup-on-failure": false,
        "history-cutoff": "2025-01-01T00:00:00.000Z",
        "policy-set-mode": "attach",
        "variable-mode": "copy",
        "workspace-prefix": null,
        "workspace-suffix": "-imported-2026",
        "source-workspace-id": "ws-ecz3ZMRwbJTAX9qx",
        "destination-workspace-id": null,
        "source-organization-id": "org-PQoehrV8LtVcmAyk",
        "destination-organization-id": "org-DWPj984qNYyZJHBC",
        "destination-project-id": "prj-4asDFjRKs86bvzYa",
        "created-at": "2026-04-06T16:00:05.440Z",
        "updated-at": "2026-04-06T16:00:05.473Z"
      },
      "relationships": {
        "events": {
          "meta": {}
        }
      }
    },
    {
      "id": "wt-eqrgP1sKSQJkGLBm",
      "type": "workspace-transfers",
      "attributes": {
        "status": "completed",
        "pause-reason": null,
        "approval-mode": "required",
        "cleanup-on-failure": false,
        "history-cutoff": "2025-01-01T00:00:00.000Z",
        "policy-set-mode": "attach",
        "variable-mode": "copy",
        "workspace-prefix": null,
        "workspace-suffix": "-imported-2026",
        "source-workspace-id": "ws-wR1NNkTHWhNoPZwz",
        "destination-workspace-id": "ws-mRqkVXjF2je8PHaX",
        "source-organization-id": "org-PQoehrV8LtVcmAyk",
        "destination-organization-id": "org-DWPj984qNYyZJHBC",
        "destination-project-id": "prj-4asDFjRKs86bvzYa",
        "created-at": "2026-04-06T15:50:06.623Z",
        "updated-at": "2026-04-06T15:58:08.203Z"
      },
      "relationships": {
        "events": {
          "meta": {}
        }
      }
    }
  ],
  "links": {
    "self": "https://tfe.example.com/api/v2/workspace-transfers?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://tfe.example.com/api/v2/workspace-transfers?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://tfe.example.com/api/v2/workspace-transfers?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 2
    }
  }
}

Get the status of a workspace transfer

This endpoint shows the details for a specific workspace transfer.

GET /workspace-transfers/:transfer_id

Parameter	Description
`:transfer_id`	The ID of the transfer run to retrieve.

Query parameters

This endpoint accepts the following query parameters in the URL:

Parameter	Description
`include`	Use `events` to retrieve the full audit trail for the transfer. This audit trails includes information such as errors, retries, and user actions.

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://tfe.example.com/api/v2/workspace-transfers/wt-rK3p7mWBf2xNqJvL?include=events

Sample response

{
  "data": {
    "id": "wt-rK3p7mWBf2xNqJvL",
    "type": "workspace-transfers",
    "attributes": {
      "status": "completed",
      "pause-reason": null,
      "approval-mode": "required",
      "cleanup-on-failure": false,
      "history-cutoff": "2025-01-01T00:00:00.000Z",
      "policy-set-mode": "attach",
      "variable-mode": "copy",
      "workspace-prefix": null,
      "workspace-suffix": "-imported-2026",
      "source-workspace-external-id": "ws-1Km75umr8xuDMKCo",
      "destination-workspace-external-id": "ws-h3CpCjCFhns7yNpi",
      "source-organization-external-id": "org-Ke21q7B8XrCsoaWW",
      "destination-organization-external-id": "org-6ERerwwjr2NNdRGn",
      "destination-project-external-id": "prj-i2hqWP1RKNZ2EiFJ",
      "created-at": "2026-02-01T14:30:00.000Z",
      "updated-at": "2026-02-01T15:02:05.000Z"
    },
    "relationships": {
      "events": {
        "data": [
          {
            "id": "wte-2eXYiwA4e9gjRaaX",
            "type": "workspace-transfer-events"
          },
          {
            "id": "wte-BMcCQL72AJA7s64q",
            "type": "workspace-transfer-events"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "wte-Xk9mP2nW",
      "type": "workspace-transfer-events",
      "attributes": {
        "event-type": "created",
        "operation-name": null,
        "message": null,
        "user-id": "user-ad2a1vBKvJ4PahZC",
        "created-at": "2026-02-01T14:30:00.000Z"
      }
    },
    {
      "id": "wte-Ht3vR8qJ",
      "type": "workspace-transfer-events",
      "attributes": {
        "event-type": "started",
        "operation-name": null,
        "message": null,
        "user-id": null,
        "created-at": "2026-02-01T14:30:05.000Z"
      }
    },
    ##...
  ]
}

Cancel a transfer

This endpoint lets you cancel a transfer anytime before the cleanup phase.

When you transfer a workspace, Terraform Enterprise locks the source workspace and makes a copy to the destination organization. If you cancel the operation early, Terraform leaves both the source and destination workspace, and you must manually clean up destination workspace.

Call the following endpoint to cancel a transfer at anytime before the cleanup phase:

POST /workspace-transfers/:transfer_id/actions/cancel

Parameter	Description
`:transfer_id`	The ID of the transfer run to cancel.

Status	Response	Reason
200	Empty body	Successfully canceled the workspace transfer.
409	JSON API error object	The source workspace cleanup has already begun.

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://tfe.example.com/api/v2/workspace-transfers//wt-rK3p7mWBf2xNqJvL/actions/cancel

Resume a paused transfer

Call the following endpoint to resume a transfer in a paused state:

POST /workspace-transfers/:transfer_id/actions/resume

Terraform Enterprise pauses a transfer in the following cases:

data.attributes.approval-mode is set to required when calling the POST /workspace-transfers endpoint. Refer to the Transfer a workspace for more information.
When Terraform Enterprise encounters an error that requires manual investigation.

You cannot resume a canceled transfer.

Parameter	Description
`:transfer_id`	The ID of the transfer run to resume.

Status	Response	Reason
200	Empty body	Successfully resumed the workspace transfer.
409	JSON API error object	The source workspace is not paused.

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://tfe.example.com/api/v2/workspace-transfers/wt-rK3p7mWBf2xNqJvL/actions/resume

Sample response

{
  "data": {
    "id": "wt-eqrgP1sKSQJkGLBm",
    "type": "workspace-transfers",
    "attributes": {
      "status": "in_progress",
      "pause-reason": null,
      "approval-mode": "required",
      "cleanup-on-failure": false,
      "history-cutoff": "2025-01-01T00:00:00.000Z",
      "policy-set-mode": "attach",
      "variable-mode": "copy",
      "workspace-prefix": null,
      "workspace-suffix": "-imported-2026",
      "source-workspace-id": "ws-wR1NNkTHWhNoPZwz",
      "destination-workspace-id": "ws-mRqkVXjF2je8PHaX",
      "source-organization-id": "org-PQoehrV8LtVcmAyk",
      "destination-organization-id": "org-DWPj984qNYyZJHBC",
      "destination-project-id": "prj-4asDFjRKs86bvzYa",
      "created-at": "2026-04-06T15:50:06.623Z",
      "updated-at": "2026-04-06T15:54:33.613Z"
    },
    "relationships": {
      "events": {
        "meta": {}
      }
    }
  }
}