---
title: "Get a template by slug with its versions, compatibility, caps, installed tools and plan clamping (the API key’s organization)"
method: GET
path: "/v1/templates/{slug}"
tags: ["Templates"]
---

# Get a template by slug with its versions, compatibility, caps, installed tools and plan clamping (the API key’s organization)

`GET /v1/templates/{slug}`

## Request

- Base URL: `https://api.shardflux.dev`
- URL: `https://api.shardflux.dev/v1/templates/{slug}`
- Auth: HTTP bearer

The organization’s own template shadows a platform template of the same slug (like `open`); `open_resolves_to` is what `open` would use now. Unpublished versions appear only for owners/admins of the owning organization. 404 outside the organization.

## Path parameters

- `slug` string, required

## Query parameters

- `include_archived` boolean
- `owner` 'platform' | 'organization'

## Response `200`

Default Response

- object
  - `id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `slug` string, required
  - `name` string, required
  - `owner` 'platform' | 'organization', required
  - `organization_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
  - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `archived_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `shadowed_by_organization_template` boolean, required: Platform template whose slug the caller’s organization template currently wins for `open` (resolution prefers the organization’s published version).
  - `defaults` object, required: Mutable template-level defaults (versions are immutable). Null fields fall back to the version and platform defaults.
    - `memory_mib` integer, nullable, required: Memory of a new start without caps.memory_mib (overrides the version’s default_caps.memory_mib_base).
    - `idle_policy` string, nullable, required: Idle policy of a workspace that sets none: adaptive, never or fixed:<seconds>.
  - `computer_use` boolean, required: : the template’s computer use switch for its workspaces (a workspace may override it). Set by the owning organization; platform templates are off.
  - `open_version` object, nullable, required
    - `id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `version` integer, required
    - `state` 'unpublished' | 'published' | 'archived', required
    - `architecture` string, required
    - `artifact_sha256` string, required: SHA-256 of the version manifest (its immutable identity).
    - `description` string, nullable, required
    - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `published_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `archived_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `is_open_version` boolean, required: The version `open` picks for a new workspace of this template (latest published, not archived).
    - `caps` object, required: Template limits (null = the template adds no limit).
      - `cpu_millis_max` integer, nullable, required
      - `memory_mib_max` integer, nullable, required
      - `disk_gib_max` integer, nullable, required
    - `default_caps` object, nullable, required: Defaults from the manifest (memory_mib_base = boot memory of a new workspace).
      - `cpu_millis_ceiling` integer, nullable, required
      - `memory_mib_base` integer, nullable, required
      - `memory_mib_ceiling` integer, nullable, required
      - `disk_gib` integer, nullable, required
    - `effective_ceilings` object, nullable, required: Ceilings a new workspace without user caps would get now: min(template limit, plan limit).
      - `cpu_millis` integer, required
      - `memory_mib` integer, required
      - `disk_gib` integer, required
      - `sources` object, required
        - `cpu_millis` 'template' | 'user' | 'plan', required
        - `memory_mib` 'template' | 'user' | 'plan', required
        - `disk_gib` 'template' | 'user' | 'plan', required
    - `plan_clamped` object, required: Resources where the caller’s plan is below what the template states (limit, else manifest default ceiling), with the plan value. Empty = no clamping.
      - `cpu_millis` integer
      - `memory_mib` integer
      - `disk_gib` integer
    - `compatibility` object, required: Runtime requirements exactly as recorded in the version manifest (null = not recorded).
      - `manifest_schema` string, nullable, required
      - `architecture` string, required
      - `kernel` object, nullable, required
        - `release` string, nullable, required
        - `sha256` string, nullable, required
      - `guest_agent` object, nullable, required
        - `version` string, nullable, required
        - `sha256` string, nullable, required
        - `vsock_port` integer, nullable, required
      - `rootfs` object, nullable, required
        - `format` string, nullable, required
        - `bytes` integer, nullable, required
        - `sha256` string, nullable, required
      - `firecracker` string, nullable, required: Required Firecracker version when the manifest states one.
      - `runtime_class` string, nullable, required: Runtime class when the manifest states one.
    - `installed_tools` object[], required: Tool versions recorded in the manifest at build time.
      - `name` string, required
      - `version` string, required
    - `build_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
    - `publishable` boolean, required: Unpublished, not archived and produced by a build whose scan and compatibility checks passed (a registered `published` build, or a legacy `succeeded` one).
    - `manifest_schema` string, nullable, required: shardflux.template.v1 or shardflux.template.v2.
    - `disk_layouts` DiskLayout[], required: Layouts a new workspace of this version may use (a manifest without the field: legacy only).
    - `source` TemplateSource, required: How the version was produced: a recipe build, a saved workspace (or draft), or git (reserved).
      - `kind` 'recipe' | 'workspace' | 'git', required
      - `recipe` object, nullable, required
        - `recipe_sha256` string, nullable, required
        - `build_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
      - `workspace` object, nullable, required
        - `workspace_id` string, uuid, required: UUIDv7, lowercase canonical form.
        - `workspace_key` string, nullable, required
        - `checkpoint_id` string, nullable, required
        - `draft` boolean, required
        - `saved_by` object, nullable, required
          - `principal_type` string, required
          - `principal_id` string, required
        - `scrub` object, nullable, required
          - `policy` string, required
          - `removed_count` integer, required
          - `removed_bytes` integer, required
        - `acknowledged_scan_findings` string[], required
    - `base` object, nullable, required: Lineage: the version this one was built on (manifest `base`); null for platform roots.
      - `name` string, required
      - `version` string, required
      - `manifest_sha256` string, nullable, required
      - `rootfs_sha256` string, nullable, required
    - `defaults` TemplateDefaults, required: Manifest v2 `defaults`. Versions without them report the T1 defaults.
      - `lifetime` 'persistent' | 'session', required: persistent: kept until deleted (default). session: discarded when the session ends (close(), idle timeout or draft discard;).
      - `idle_timeout_seconds` integer, nullable, required
      - `limits` object, nullable, required: Ceilings of every admission of a workspace of the version (clamped, never refused;).
        - `cpu_millis_ceiling` integer, required
        - `memory_mib_ceiling` integer, required
        - `disk_gib` integer, required
      - `egress` TemplateEgressDefault, required: The template’s workspace network ceiling: the cell intersects it with the effective egress policy.
        - `mode` 'allowlist' | 'none', required
        - `allow_hosts` string[], required: Normalized (lowercase, sorted); empty for none.
      - `agent_tools` unknown, required
    - `settings` TemplateSettings, required: What a workspace of the version gets when it opens, every key present. `env` is the effective template env (a recipe v2 version: its languages’ build env, then its own env).
      - `env` object, required
      - `inputs` object, required
      - `start` TemplateStartCommand[], required
        - `name` string, required
        - `when` 'create' | 'boot' | 'resume', required
        - `run` string, required
        - `user` string, nullable, required: null: the template’s default user.
        - `cwd` string, nullable, required
        - `timeout_seconds` integer, required
      - `services` object, required
      - `defaults` TemplateDefaults, required: Manifest v2 `defaults`. Versions without them report the T1 defaults.
        - `lifetime` 'persistent' | 'session', required: persistent: kept until deleted (default). session: discarded when the session ends (close(), idle timeout or draft discard;).
        - `idle_timeout_seconds` integer, nullable, required
        - `limits` object, nullable, required: Ceilings of every admission of a workspace of the version (clamped, never refused;).
          - `cpu_millis_ceiling` integer, required
          - `memory_mib_ceiling` integer, required
          - `disk_gib` integer, required
        - `egress` TemplateEgressDefault, required: The template’s workspace network ceiling: the cell intersects it with the effective egress policy.
          - `mode` 'allowlist' | 'none', required
          - `allow_hosts` string[], required: Normalized (lowercase, sorted); empty for none.
        - `agent_tools` unknown, required
    - `immutable` object, nullable, required: Immutable paths: the version’s read-only directories and its image; null when the version declares none. Workspaces of the template mount the image of the open version (is_open_version), so publishing a version updates them at their next cold boot or resume, and archiving it rolls them back. A write under one of these paths answers 409 conflict, details.reason read_only_path.
      - `paths` string[], required: The directories every workspace of the template mounts read-only from its newest published version, in byte order.
      - `bytes` integer, required: Size of the version’s immutable image (counts toward template storage).
    - `files` TemplateFilesSummary, required: The version’s file list (the tree and diff routes read it).
      - `state` 'unavailable' | 'pending' | 'loading' | 'loaded' | 'failed', required: unavailable: no file list (versions from before manifest v2 that were not backfilled); pending/loading: being indexed (tree/diff answer 409 file_list_indexing); loaded; failed.
      - `entries` integer, nullable, required
      - `total_file_bytes` integer, nullable, required
    - `rootfs_bytes` integer, nullable, required: The root image size (for layers versions: the platform base’s).
    - `chain` object[], required: The org layers of this version’s chain, bottom to top (empty for images).
      - `layer_id` string, uuid, required: UUIDv7, lowercase canonical form.
      - `bytes` integer, required
      - `introduced_in_version` integer, nullable, required
    - `storage` TemplateStorage, required: Storage of a template version.
      - `format` 'image' | 'layers', required: layers: org layers stacked on a platform base; image: a full image (platform bases, legacy-base builds, versions from before layers).
      - `org_bytes` integer, required: This version’s organization bytes: the sum of its chain’s org layers (an image: its delta over its base; a platform version: 0).
      - `new_bytes` integer, required: Bytes this version introduced: its chain’s org layers that its base version’s chain does not have.
      - `base_bytes` integer, nullable, required: The platform base image (shared, never billed; informational).
      - `template_bytes` integer, required: Distinct bytes across every version of this template (a shared layer counted once).
      - `org_template_bytes` integer, required: The organization’s template storage (counts toward retained_state_gib).
      - `plan_storage_bytes` integer, nullable, required: retained_state_gib x 2^30 of the organization’s plan (null when the plan has none).
      - `template_share` number, nullable, required: template_bytes / plan_storage_bytes.
      - `org_share` number, nullable, required: org_template_bytes / plan_storage_bytes.
      - `warnings` TemplateStorageWarning[], required
  - `draft` object, nullable, required: The template’s live draft (GET …/templates/{slug}/draft for the full view); null when there is none.
    - `workspace_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `workspace_key` string, required
    - `observed_state` string, required
    - `base_version` object, required: The draft base: the template version the draft (and its test instances) run on.
      - `id` string, uuid, required: UUIDv7, lowercase canonical form.
      - `template_id` string, uuid, required: UUIDv7, lowercase canonical form.
      - `slug` string, required
      - `version` integer, required
    - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `category` 'os' | 'stack', nullable, required: Platform templates: os (a bare operating system) or stack (preinstalled tools). Organization templates: null.
  - `plan` object, nullable, required
    - `plan_key` string, required
    - `catalog_version` string, required
  - `open_resolves_to` object, nullable, required: What `open({template: slug})` resolves to for this organization right now (may be the other template of the same slug).
    - `template_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `template_version_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `version` integer, required
    - `owner` 'platform' | 'organization', required
  - `versions` object[], required: Newest first. Unpublished versions only for owners/admins of the owning organization; archived only with include_archived.
    - `id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `version` integer, required
    - `state` 'unpublished' | 'published' | 'archived', required
    - `architecture` string, required
    - `artifact_sha256` string, required: SHA-256 of the version manifest (its immutable identity).
    - `description` string, nullable, required
    - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `published_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `archived_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `is_open_version` boolean, required: The version `open` picks for a new workspace of this template (latest published, not archived).
    - `caps` object, required: Template limits (null = the template adds no limit).
      - `cpu_millis_max` integer, nullable, required
      - `memory_mib_max` integer, nullable, required
      - `disk_gib_max` integer, nullable, required
    - `default_caps` object, nullable, required: Defaults from the manifest (memory_mib_base = boot memory of a new workspace).
      - `cpu_millis_ceiling` integer, nullable, required
      - `memory_mib_base` integer, nullable, required
      - `memory_mib_ceiling` integer, nullable, required
      - `disk_gib` integer, nullable, required
    - `effective_ceilings` object, nullable, required: Ceilings a new workspace without user caps would get now: min(template limit, plan limit).
      - `cpu_millis` integer, required
      - `memory_mib` integer, required
      - `disk_gib` integer, required
      - `sources` object, required
        - `cpu_millis` 'template' | 'user' | 'plan', required
        - `memory_mib` 'template' | 'user' | 'plan', required
        - `disk_gib` 'template' | 'user' | 'plan', required
    - `plan_clamped` object, required: Resources where the caller’s plan is below what the template states (limit, else manifest default ceiling), with the plan value. Empty = no clamping.
      - `cpu_millis` integer
      - `memory_mib` integer
      - `disk_gib` integer
    - `compatibility` object, required: Runtime requirements exactly as recorded in the version manifest (null = not recorded).
      - `manifest_schema` string, nullable, required
      - `architecture` string, required
      - `kernel` object, nullable, required
        - `release` string, nullable, required
        - `sha256` string, nullable, required
      - `guest_agent` object, nullable, required
        - `version` string, nullable, required
        - `sha256` string, nullable, required
        - `vsock_port` integer, nullable, required
      - `rootfs` object, nullable, required
        - `format` string, nullable, required
        - `bytes` integer, nullable, required
        - `sha256` string, nullable, required
      - `firecracker` string, nullable, required: Required Firecracker version when the manifest states one.
      - `runtime_class` string, nullable, required: Runtime class when the manifest states one.
    - `installed_tools` object[], required: Tool versions recorded in the manifest at build time.
      - `name` string, required
      - `version` string, required
    - `build_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
    - `publishable` boolean, required: Unpublished, not archived and produced by a build whose scan and compatibility checks passed (a registered `published` build, or a legacy `succeeded` one).
    - `manifest_schema` string, nullable, required: shardflux.template.v1 or shardflux.template.v2.
    - `disk_layouts` DiskLayout[], required: Layouts a new workspace of this version may use (a manifest without the field: legacy only).
    - `source` TemplateSource, required: How the version was produced: a recipe build, a saved workspace (or draft), or git (reserved).
      - `kind` 'recipe' | 'workspace' | 'git', required
      - `recipe` object, nullable, required
        - `recipe_sha256` string, nullable, required
        - `build_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
      - `workspace` object, nullable, required
        - `workspace_id` string, uuid, required: UUIDv7, lowercase canonical form.
        - `workspace_key` string, nullable, required
        - `checkpoint_id` string, nullable, required
        - `draft` boolean, required
        - `saved_by` object, nullable, required
          - `principal_type` string, required
          - `principal_id` string, required
        - `scrub` object, nullable, required
          - `policy` string, required
          - `removed_count` integer, required
          - `removed_bytes` integer, required
        - `acknowledged_scan_findings` string[], required
    - `base` object, nullable, required: Lineage: the version this one was built on (manifest `base`); null for platform roots.
      - `name` string, required
      - `version` string, required
      - `manifest_sha256` string, nullable, required
      - `rootfs_sha256` string, nullable, required
    - `defaults` TemplateDefaults, required: Manifest v2 `defaults`. Versions without them report the T1 defaults.
      - `lifetime` 'persistent' | 'session', required: persistent: kept until deleted (default). session: discarded when the session ends (close(), idle timeout or draft discard;).
      - `idle_timeout_seconds` integer, nullable, required
      - `limits` object, nullable, required: Ceilings of every admission of a workspace of the version (clamped, never refused;).
        - `cpu_millis_ceiling` integer, required
        - `memory_mib_ceiling` integer, required
        - `disk_gib` integer, required
      - `egress` TemplateEgressDefault, required: The template’s workspace network ceiling: the cell intersects it with the effective egress policy.
        - `mode` 'allowlist' | 'none', required
        - `allow_hosts` string[], required: Normalized (lowercase, sorted); empty for none.
      - `agent_tools` unknown, required
    - `settings` TemplateSettings, required: What a workspace of the version gets when it opens, every key present. `env` is the effective template env (a recipe v2 version: its languages’ build env, then its own env).
      - `env` object, required
      - `inputs` object, required
      - `start` TemplateStartCommand[], required
        - `name` string, required
        - `when` 'create' | 'boot' | 'resume', required
        - `run` string, required
        - `user` string, nullable, required: null: the template’s default user.
        - `cwd` string, nullable, required
        - `timeout_seconds` integer, required
      - `services` object, required
      - `defaults` TemplateDefaults, required: Manifest v2 `defaults`. Versions without them report the T1 defaults.
        - `lifetime` 'persistent' | 'session', required: persistent: kept until deleted (default). session: discarded when the session ends (close(), idle timeout or draft discard;).
        - `idle_timeout_seconds` integer, nullable, required
        - `limits` object, nullable, required: Ceilings of every admission of a workspace of the version (clamped, never refused;).
          - `cpu_millis_ceiling` integer, required
          - `memory_mib_ceiling` integer, required
          - `disk_gib` integer, required
        - `egress` TemplateEgressDefault, required: The template’s workspace network ceiling: the cell intersects it with the effective egress policy.
          - `mode` 'allowlist' | 'none', required
          - `allow_hosts` string[], required: Normalized (lowercase, sorted); empty for none.
        - `agent_tools` unknown, required
    - `immutable` object, nullable, required: Immutable paths: the version’s read-only directories and its image; null when the version declares none. Workspaces of the template mount the image of the open version (is_open_version), so publishing a version updates them at their next cold boot or resume, and archiving it rolls them back. A write under one of these paths answers 409 conflict, details.reason read_only_path.
      - `paths` string[], required: The directories every workspace of the template mounts read-only from its newest published version, in byte order.
      - `bytes` integer, required: Size of the version’s immutable image (counts toward template storage).
    - `files` TemplateFilesSummary, required: The version’s file list (the tree and diff routes read it).
      - `state` 'unavailable' | 'pending' | 'loading' | 'loaded' | 'failed', required: unavailable: no file list (versions from before manifest v2 that were not backfilled); pending/loading: being indexed (tree/diff answer 409 file_list_indexing); loaded; failed.
      - `entries` integer, nullable, required
      - `total_file_bytes` integer, nullable, required
    - `rootfs_bytes` integer, nullable, required: The root image size (for layers versions: the platform base’s).
    - `chain` object[], required: The org layers of this version’s chain, bottom to top (empty for images).
      - `layer_id` string, uuid, required: UUIDv7, lowercase canonical form.
      - `bytes` integer, required
      - `introduced_in_version` integer, nullable, required
    - `storage` TemplateStorage, required: Storage of a template version.
      - `format` 'image' | 'layers', required: layers: org layers stacked on a platform base; image: a full image (platform bases, legacy-base builds, versions from before layers).
      - `org_bytes` integer, required: This version’s organization bytes: the sum of its chain’s org layers (an image: its delta over its base; a platform version: 0).
      - `new_bytes` integer, required: Bytes this version introduced: its chain’s org layers that its base version’s chain does not have.
      - `base_bytes` integer, nullable, required: The platform base image (shared, never billed; informational).
      - `template_bytes` integer, required: Distinct bytes across every version of this template (a shared layer counted once).
      - `org_template_bytes` integer, required: The organization’s template storage (counts toward retained_state_gib).
      - `plan_storage_bytes` integer, nullable, required: retained_state_gib x 2^30 of the organization’s plan (null when the plan has none).
      - `template_share` number, nullable, required: template_bytes / plan_storage_bytes.
      - `org_share` number, nullable, required: org_template_bytes / plan_storage_bytes.
      - `warnings` TemplateStorageWarning[], required
  - `versions_truncated` boolean, required

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

[API](https://skmtc.dev/shardflux/apis/shardflux-api.md) · [All operations](https://skmtc.dev/shardflux/apis/shardflux-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shardflux/apis/shardflux-api/revisions/ea685f7b39c4?raw)