---
title: "Begin a stopped-workspace file replacement"
method: POST
path: "/v1/research-workspaces/{id}/transfers"
tags: ["Research workspaces"]
---

# Begin a stopped-workspace file replacement

`POST /v1/research-workspaces/{id}/transfers`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/research-workspaces/{id}/transfers`
- Auth: HTTP bearer

Available only when included-10gb-v1 or r2-standard-10gb-account-v1 is explicitly active for the deployment and workspace. Compute must be stopped. Requires a nonempty canonical version 3 archive manifest, not a generic archive upload. Retain idempotency_key, manifest and replace_revision together across retries. Previously saved files require the current storage_revision as replace_revision. Beginning a transfer does not change saved files. The SDK folder uploader prepares this canonical manifest and uploads bounded segments.

## Path parameters

- `id` string, required

## Request body

- WorkspaceTransferRequest
  - `idempotency_key` string, required: Caller-retained key without leading or trailing whitespace. Retain the same manifest and replacement revision when retrying.
  - `manifest` WorkspaceArchiveManifest, required: Version 3 canonical workspace archive commitment, limited to 16 MiB of manifest JSON. Requires a qualified archive writer. Arbitrary tar, zip or compressed bytes are not accepted. The archive permits ordered regular files, directories and confined symbolic links, with at most 10 GB of payload and 512 MiB of archive metadata. Verification checks the complete archive and inventory before replacing saved files.
    - `version` 3, required
    - `archive_sha256` string, required
    - `archive_bytes` integer, required
    - `inventory` WorkspaceArchiveInventory, required
      - `sha256` string, required: Versioned inventory digest derived from ordered paths, file bytes and metadata. The server verifies it against the uploaded archive.
      - `payload_bytes` integer, required
      - `entries` integer, required
    - `segments` WorkspaceArchiveSegment[], required
      - `sha256` string, required
      - `offset` integer, required
      - `bytes` integer, required
  - `replace_revision` integer: Observed storage_revision required to replace previously saved files. A changed revision conflicts instead of overwriting newer files.

## Response `201`

Transfer created or original intent replayed

- WorkspaceTransfer
  - `id` string, uuid, required
  - `workspace_id` string, required
  - `failure_code` string: Recorded verification failure when present. Inspect state before retrying or beginning a replacement transfer.
  - `state` 'uploading' | 'queued' | 'verifying' | 'committed' | 'abandoned', required
  - `base_revision` integer, required
  - `manifest_sha256` string, required
  - `manifest_bytes` integer, required
  - `uploaded_segments` integer[], required: Zero-based indexes already verified for this transfer. Empty when no segment is present.

## Other responses

- `default`: 400 for malformed input. 404 workspace_transfer_not_found for a missing or inaccessible transfer. 409 workspace_storage_inactive when the policy is disabled, or workspace_transfer_conflict when state, revision or retry identity changed. 413 workspace_storage_capacity when capacity is exhausted. 503 workspace_transfer_unavailable or workspace_storage_unavailable for transient failures. Authentication and rate limits apply.

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)