Workspaces

Fork a workspace into a new key (independent copy of its committed state)

Creates the target workspace (same template version and disk layout) and a fork operation on it, admitted like a start. Caps default to the source’s. lifetime is the fork’s own (default persistent): forking a session keeps its state. A file-first source is 409 not_supported_for_mode. Supports Idempotency-Key. Caps (and the memory allocation mode) default to the source’s. Held fork: with Prefer: wait=<seconds> (at most 20), holds through the terminal operation. Success returns 200 with the running target, succeeded operation and a final-epoch tool token for agent_label/tools. Otherwise returns 202 with the fresh operation. Preference-Applied confirms the wait; without it, poll as usual. A token that could not be issued is null; fetch it from the target tool-token route. Errors: 402/403/429 as for open (admitted like a start). Plan concurrency: a start the plan’s concurrent_workspaces limit refuses is queued on the request (up to 10 s) and admitted as soon as one of the organization’s workspaces frees; if none does, 429 quota_exceeded with Retry-After: 2 (retryable; details limit concurrent_workspaces, limit_value, current, retry_after_seconds, plan). Nothing was created: retry after Retry-After, with the same Idempotency-Key or a new one. With Prefer: wait the queued time counts against the wait. Memory allocation: caps.allocation_mode elastic with caps.memory_mib_held; 422 validation_failed details.field caps.allocation_mode reason allocation_mode_not_available (the organization lacks elastic memory; nothing is created or changed), reason not_supported_for_mode (file_first); details.field caps.memory_mib_held reason requires_elastic (held without elastic) or exceeds_memory_mib (held above caps.memory_mib).

post/v1/workspaces/{workspace_id}/fork

Request

  • Base URL: https://api.shardflux.dev
  • URL: https://api.shardflux.dev/v1/workspaces/{workspace_id}/fork
  • Auth: HTTP bearer

Path parameters

workspace_idstring uuid required

UUIDv7, lowercase canonical form.

Headers

preferstring

Request body

keystring required

Stable workspace key, unique per organization (e.g. ${customerId}/${projectId}).

lifetime'persistent' | 'session'

persistent: kept until deleted (default). session: discarded when the session ends (close(), idle timeout or draft discard;).

labelsobject

Searchable workspace metadata; not secrets. At most 50 labels.

agent_labelstring

Attribution label; one agent session per (workspace, principal, label).

toolsstring[]

Response

Default Response

source_workspace_idstring uuid required

UUIDv7, lowercase canonical form.

cell_endpointstring nullable required

Changes

No recorded changes to this operation across all 1 revision of this API.