---
title: "Export the recipe and settings of a template version (request form, ready to build again)"
method: GET
path: "/v1/templates/{slug}/versions/{version}/recipe"
tags: ["Templates"]
---

# Export the recipe and settings of a template version (request form, ready to build again)

`GET /v1/templates/{slug}/versions/{version}/recipe`

## Request

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

recipe: v1 {base, dockerfile, network} or the recipe v2 document (base as <slug>@<version>, languages as {id, version}, files without size, settings as stored); building it again from the same base with the same API release, while its uploads exist, gives the same recipe_sha256. null for versions saved from a workspace or published by the platform. settings: the version’s TemplateSettings. Same visibility as the version (unpublished only for owners/admins of the owning organization).

## Path parameters

- `slug` string, required
- `version` integer, required

## Query parameters

- `owner` 'platform' | 'organization'

## Response `200`

The recipe and settings a version was built from (feeds "Edit template" and `shard templates export`).

- TemplateVersionRecipe: The recipe and settings a version was built from (feeds "Edit template" and `shard templates export`).
  - `version` integer, required
  - `source_kind` 'recipe' | 'workspace' | 'git', nullable, required
  - `recipe` union, required
    - TemplateRecipeV1: Recipe v1: a Dockerfile in the host builder’s dialect (no `schema` field).
      - `base` string, required: `<template slug>@<version>`: a published, non-archived version this organization can use (its own templates first, then platform). Referenced as `FROM shardflux-base`.
      - `dockerfile` string, required: Dockerfile in the builder dialect (<= 64 KiB UTF-8): exactly one `FROM shardflux-base` (or `FROM shardflux-base:<recipe.base>`) first (ARG may precede it), then RUN (shell or JSON exec form, no flags or heredocs), ENV, ARG, WORKDIR, USER; LABEL, EXPOSE, CMD, ENTRYPOINT, MAINTAINER, STOPSIGNAL are recorded only. No COPY/ADD (no build context), no multi-stage or external images, at most 128 steps. Refusals are 422 with details.reason and line.
      - `architecture` 'x86_64': x86_64 (the default; the only one).
      - `resources` object: Builder VM bounds (the host builder’s ranges); clamped to the plan’s per-workspace limits (absent = the plan limit); timeout default 1800 s, maximum 3600 s.
        - `cpu_millis` integer: Builder range 500-16000.
        - `memory_mib` integer: Builder range 512-32768, even.
        - `disk_gib` integer: Builder maximum 200.
        - `timeout_seconds` integer
      - `network` object: Build network: none (default) or egress to the listed DNS names (example.com, *.example.com).
        - `mode` 'none' | 'egress_allowlist', required
        - `allow_hosts` string[]
    - TemplateRecipeV2: A template without a Dockerfile (docs/INTEGRATION_CONTRACTS.md): `build` changes the filesystem through the host builder's structured steps, `settings` goes into the manifest and applies when a workspace opens. This document is the body field `recipe` of POST …/template-builds, the `recipe` of GET …/templates/{slug}/versions/{v}/recipe (export), and the content of template.yaml (the same document in YAML; only clients parse YAML). In template.yaml a file entry may name a local path (`from`) instead of an upload; clients upload it and send `upload` (the API refuses `from`). Rules JSON Schema cannot express, enforced by the API with 422 validation_failed and details.reason (): input names are unique across settings.env and settings.inputs; a secret input has no default; a required input has no default; start command names are unique; `to` is not platform-owned; build.network.allow_hosts only with build "allowlist" and extra_hosts only with "auto"; the sum of every run/command script is at most 262144 bytes; start timeout_seconds sum to at most 3600; languages are in the API's language table for the base; services need a base whose guest agent has services.v1; immutable paths are not platform-owned, do not contain a platform-owned path and do not nest.
      - `schema` 'shardflux.template-recipe.v2', required
      - `base` string, required: `<template slug>@<version>`: a published, non-archived, layered-capable version this organization can use (its own templates first, then platform), e.g. ubuntu-24.04@1.
      - `build` object, required
        - `languages` object[]: Languages from the API's language table. version omitted = the table's default for the base. Compiled first, in the table's order (not this array's).
          - `id` 'python' | 'node' | 'go' | 'rust' | 'java', required
          - `version` string
        - `packages` object
          - `apt` string[]
          - `pip` object: Installed into /opt/venv (implies the python language).
            - `packages` string[]
            - `requirements` string[]: Absolute paths of requirements files inside the template (usually from files[]), installed with pip -r.
          - `npm` string[]: npm install -g (implies the node language unless the base has node).
        - `files` object[]: Uploaded files and folders, applied in this order (a later entry overwrites an earlier one).
          - `upload` string: An upload of this organization: sha256:<64 lower-case hex>.
          - `from` string: template.yaml only: a local file (kind file) or directory (kind tar) the client uploads. Refused by the API.
          - `kind` 'file' | 'tar', required
          - `to` string, required: kind file: the file's path; kind tar: the directory the archive is extracted into. Platform-owned paths are refused.
          - `owner` string: Default root.
          - `mode` string, nullable: Octal permission bits of a file (default 0644); absent or null for kind tar.
        - `steps` object[]: Named build scripts, run in this order after languages, apt, files, pip and npm.
          - `name` string, required
          - `run` string, required: Shell script run by /bin/bash -euo pipefail -c; 1..65536 bytes, no NUL.
          - `user` string: Default root.
          - `cwd` string, nullable: Absolute, clean (no '.', '..', '//' or trailing '/'), at most 1024 bytes.
          - `env` object
        - `network` object: Build network. auto (default): hosts derived from the recipe plus extra_hosts; none: no egress; allowlist: exactly allow_hosts.
          - `build` 'auto' | 'none' | 'allowlist'
          - `extra_hosts` string[]
          - `allow_hosts` string[]
      - `settings` object, required: What a workspace of the version gets when it opens (). Omitted fields are empty (recipes do not carry settings forward).
        - `env` object: Template environment for every exec, PTY, start command and service (below text inputs and the call's env).
        - `inputs` object: Open-time inputs. text: a value passed to open({inputs}); secret: a stored secret of the same name, bound to the workspace.
        - `start` object[]: Start commands: create = on a new workspace layer, boot = every cold boot, resume = every memory restore.
          - `name` string, required
          - `when` 'create' | 'boot' | 'resume', required
          - `run` string, required: Shell script run by /bin/bash -euo pipefail -c; 1..65536 bytes, no NUL.
          - `user` string, nullable: A user name or numeric uid of the template (the builder's userRE without a group).
          - `cwd` string, nullable: Absolute, clean (no '.', '..', '//' or trailing '/'), at most 1024 bytes.
          - `timeout_seconds` integer: Default: 300.
        - `services` object: Processes kept running by the guest; ready before open() returns.
        - `defaults` object: Manifest defaults (). agent_tools stays reserved (null).
          - `lifetime` 'persistent' | 'session'
          - `idle_timeout_seconds` integer, nullable
          - `limits` object, nullable: Ceilings enforced at admission (clamped).
            - `cpu_millis_ceiling` integer, required
            - `memory_mib_ceiling` integer, required
            - `disk_gib` integer, required
          - `egress` object, nullable: Workspace network ceiling: internet = no ceiling (stored as null), allowlist = only allow_hosts (TCP, any port), none = no egress.
            - `mode` 'internet' | 'allowlist' | 'none', required
            - `allow_hosts` string[]
          - `agent_tools` unknown
      - `immutable` string[]: Directories every workspace of the template mounts read-only from the template's newest published version: workspaces pick up a newer version when they cold-boot or resume. Not `/`, not equal to or under /proc, /sys, /dev, /run, /tmp, /lost+found or a platform-owned path, not containing a platform-owned path, none equal to or containing another (422 invalid_path). Omitted: the list of the template's newest published version. A version keeps every path of that list (422 immutable_path_removed) and a non-empty list needs a base whose guest agent has immutable_paths.v1 (422 immutable_paths_unsupported_base). Each path is a directory in the built filesystem.
      - `resources` object: Builder VM bounds, exactly as recipe v1 `resources` (not part of recipe_sha256).
        - `cpu_millis` integer
        - `memory_mib` integer
        - `disk_gib` integer
        - `timeout_seconds` integer
  - `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

## 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)