Workspaces

Save a layered workspace as the next version of an organization template

Everything in the workspace becomes template content (its whole filesystem, minus the sf-scrub.v1 list, the contents of /proc, /sys, /dev, /run and /tmp, and shared-volume contents), stored as one new org layer on the workspace’s template chain. A running workspace is captured briefly (operation, layer_snapshot); a suspended one uses its current checkpoint; checkpoint_id saves a committed checkpoint instead. 202 SaveAsTemplateResponse: poll the build. Owners/admins and API keys with a tool permission (403 otherwise). Immutable paths: the new version declares the target template’s open version’s immutable paths (else the workspace’s version’s); their content comes from that template’s newest published version, not from the workspace (a draft publish keeps the draft’s own content). Errors: 409 legacy_disk_layout, workspace_not_running, operation_in_progress, not_supported_for_mode (file-first), template_archived, 422 platform_template_slug, invalid_defaults, too_many_acknowledged_findings, invalid_path, immutable_paths_unsupported_base (the workspace’s base has no guest agent with immutable_paths.v1; details.base), 429 rate_limited (template_build_queue_full: already 10 builds queued past the plan’s concurrent_template_builds; retryable, Retry-After; a build past the plan’s slots is accepted and waits, its queue gives the position and expected wait). Supports Idempotency-Key.

post/v1/workspaces/{workspace_id}/save-as-template

Request

  • Base URL: https://api.shardflux.dev
  • URL: https://api.shardflux.dev/v1/workspaces/{workspace_id}/save-as-template
  • Auth: HTTP bearer

Path parameters

workspace_idstring uuid required

UUIDv7, lowercase canonical form.

Request body

template_slugstring required

Organization template to save into (created when absent; platform slugs are refused).

display_namestring

Template name when this save creates the template.

descriptionstring

The version description (default: the source version’s).

checkpoint_idstring uuid

A committed checkpoint of this workspace to save instead of its current state.

auto_publishboolean
acknowledged_scan_findingsstring[]

Up to 200 absolute paths the credential scan may report without failing the build (recorded in the manifest).

Response

operation: the capture (layer_snapshot) of a running workspace, null otherwise. build: poll GET …/template-builds/{id} until registration.state is registered.

Changes

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