DigitalOcean API (unofficial showcase)
POST/v2/agents/sessions/{session_id}/workspace/transfers

Start a staged (large-file) workspace transfer.

Creates an asynchronous, object-storage-backed transfer for payloads larger than the streaming path supports (> ~50 MiB). Bulk bytes never traverse harness-api: the client PUTs/GETs presigned DO Spaces URLs directly.

Set direction to upload or download.

  • upload: responds 201 with transfer_id + part_size; the client then requests per-part presigned PUT URLs, uploads them to Spaces, and calls commit.
  • download: responds 202 with transfer_id; the client polls GET until completed and then fetches download_url from Spaces.

Upload and cancel currently return 501 until the sandbox backend RPCs ship; download is live.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 6 body fields
session_idstringrequired
The session UUID.
directionstringrequired
Transfer direction.
Allowed:uploaddownload
pathstringrequired
Workspace-relative path. Destination for upload, source for download. Paths that escape the workspace root are rejected.
is_archivebooleanoptional
Upload only. When true, the payload is a tar the guest extracts at `path`.
as_archivebooleanoptional
Download only. When true, `path` is exported as a tar stream.
size_bytesstringoptional
Optional total payload size. Validated against the maximum staged object size (50 GiB); a larger value returns 413.
sha256stringoptional
Optional lowercase hex SHA-256 of the full payload. If set on an upload, it must match on commit.

15 status codes
201Upload transfer created; proceed to request part upload URLs.
transfer_idstringoptional
Opaque id used on all subsequent calls.
directionstringoptional
Allowed:uploaddownload
statusstringoptional
Allowed:pendingin_progresscompletedfailed
upload_idstringoptional
Upload only. Multipart upload id (informational).
part_sizeintegeroptional
Upload only. Split the payload into parts of this size; the last part may be smaller.
expires_atstringoptional
Transfer credential window.
202Download transfer accepted; poll the transfer until completed.
transfer_idstringoptional
Opaque id used on all subsequent calls.
directionstringoptional
Allowed:uploaddownload
statusstringoptional
Allowed:pendingin_progresscompletedfailed
upload_idstringoptional
Upload only. Multipart upload id (informational).
part_sizeintegeroptional
Upload only. Split the payload into parts of this size; the last part may be smaller.
expires_atstringoptional
Transfer credential window.
400Missing/invalid direction or path, or invalid JSON.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
402The team is blocked by the prepayment gate.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
403Path resolves outside the workspace, or the session belongs to another team.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404The resource was not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
409Session has no sandbox, or the sandbox is not ready.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
413Declared size exceeds the maximum staged object size.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
423This session is unavailable; contact support.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
501Staged transfer (or this direction) is not supported by the active sandbox driver.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
502Upstream sandbox transfer coordination failed.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned: Missing/invalid direction or path, or invalid JSON. A 401 is returned: Authentication failed due to invalid credentials. A 402 is returned: The team is blocked by the prepayment gate. A 403 is returned: Path resolves outside the workspace, or the session belongs to another team. A 404 is returned: The resource was not found. A 409 is returned: Session has no sandbox, or the sandbox is not ready. A 413 is returned: Declared size exceeds the maximum staged object size. A 423 is returned: This session is unavailable; contact support. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. A 501 is returned: Staged transfer (or this direction) is not supported by the active sandbox driver. A 502 is returned: Upstream sandbox transfer coordination failed. Any other status is an error: There was an unexpected error.