---
title: "List the templates an organization can use (platform + its own), with the version `open` picks (the API key’s organization)"
method: GET
path: "/v1/templates"
tags: ["Templates"]
---

# List the templates an organization can use (platform + its own), with the version \`open\` picks (the API key’s organization)

`GET /v1/templates`

## Request

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

Archived templates only with include_archived=true. Ordered by id; cursor pagination.

## Query parameters

- `limit` integer
- `cursor` string
- `include_archived` boolean
- `owner` 'platform' | 'organization'

## Response `200`

Default Response

- object
  - `data` object[], required
    - `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.
  - `next_cursor` string, nullable, 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)