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).
Request
- Base URL: https://api.shardflux.dev
- URL: https://api.shardflux.dev/v1/workspaces/{workspace_id}/fork
- Auth: HTTP bearer
Path parameters
UUIDv7, lowercase canonical form.
Headers
Request body
Response
Default Response
Changes
No recorded changes to this operation across all 1 revision of this API.