Templates API: Build and Manage Sandbox Templates

Templates are the starting point for every sandbox. You build a template from an OCI image reference — FissionPlane resolves the tag to an immutable digest, runs your build recipe inside a VM, captures a warm snapshot, and stores the resulting artifact. You then create sandboxes from the alias or artifact ID, and every sandbox starts from the exact bytes captured at build time. All template endpoints are on the control plane: https://<your-control-plane-url>/v1. Authenticate with your organisation API key in the X-API-Key header, or an OIDC bearer token in Authorization: Bearer.

Builds are asynchronous. After you start a build with POST /v1/templates/builds, poll GET /v1/templates/builds/{buildId} for status and tail output with GET /v1/templates/builds/{buildId}/logs until the build reaches a terminal state.

POST /v1/templates/builds

Starts an asynchronous template build from an OCI image. The image tag is resolved to an immutable digest immediately and is never re-consulted. If you supply an alias, FissionPlane atomically re-points the alias to the new artifact when the build succeeds — sandboxes being created from the alias mid-build continue to resolve to the previous artifact.

curl -X POST https://api.example.com/v1/templates/builds \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "node:22",
    "alias": "node-tools",
    "steps": [
      {"command": "npm install --global pnpm"},
      {"command": "pnpm --version"}
    ],
    "start_command": "node server.js",
    "ready_command": "curl -sf http://localhost:3000/health"
  }'

Request body

string

required

OCI image reference, for example node:22 or registry.example.com/myapp:v1.2.3. The tag is resolved to a digest when the build starts.

string

Template alias to point at the new artifact when the build succeeds. Must match ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$. If the alias already exists it is re-pointed atomically on success.

object[]

Ordered recipe steps executed inside the build VM. Up to 128 steps.

Show step fields

string

required

The command to run for this step.

object

Environment variables set for this step only. Keys and values are strings.

string

Command started at boot before the warm snapshot is captured. The captured memory image includes this process already running, so sandboxes resume into a pre-warmed state.

string

Readiness probe that the warm-up phase waits for before capture. The snapshot is taken only once this command exits zero, so resumed sandboxes start past this point.

object

Compute shape for sandboxes created from this template.

Show resources fields

integer

Number of virtual CPUs. Minimum 1.

integer

Memory in mebibytes. Minimum 128.

Response — 201 Created

string

required

24-character NanoID for this build. Use it to poll status and read logs.

string

required

Initial status, always queued. Transitions to building, then succeeded or failed.

string

required

The image reference as you supplied it.

string

The resolved immutable digest, once the builder has resolved it.

string

The alias requested, if any.

string

required

ISO 8601 timestamp.

Error codes: 400 malformed request · 401 unauthenticated · 403 forbidden · 429 rate limited

GET /v1/templates/builds/

Gets the current status of a template build. Poll this endpoint after starting a build to detect when it reaches a terminal state.

curl https://api.example.com/v1/templates/builds/<build-id> \
  -H "X-API-Key: <your-api-key>"

Path parameters

string

required

The 24-character build NanoID returned by POST /v1/templates/builds.

Response — 200 OK

string

required

Build identifier.

string

required

One of queued, building, succeeded, or failed. queued and building are in progress; succeeded and failed are terminal.

string

The produced template artifact (sha256:...). Present only once status is succeeded.

string

A description of what failed. Present only when status is failed.

string

ISO 8601 timestamp when the build reached a terminal state.

Error codes: 401 unauthenticated · 404 not found

GET /v1/templates/builds//logs

Returns log entries from a template build starting at offset. Poll this endpoint alongside GET /v1/templates/builds/{buildId} to tail build output. A call at the current end of the log returns an empty page and is not an error.

curl "https://api.example.com/v1/templates/builds/<build-id>/logs?offset=0" \
  -H "X-API-Key: <your-api-key>"

Path parameters

string

required

The 24-character build NanoID.

Query parameters

integer

Entry offset from which to start reading. Default 0. Pass the next_offset from the previous response to read the next page.

Response — 200 OK

object[]

required

Log entries for this page.

Show entry fields

string

required

ISO 8601 timestamp.

string

required

Log line text.

integer

required

Pass as offset on the next poll to continue reading from where this page left off.

Error codes: 401 unauthenticated · 404 not found

GET /v1/templates

Lists templates visible to your organisation, most recently created first.

curl "https://api.example.com/v1/templates?limit=20" \
  -H "X-API-Key: <your-api-key>"

Query parameters

integer

Page size. Between 1 and 100, default 20.

string

Opaque cursor from a previous page’s next_cursor. Omit for the first page.

Response — 200 OK

Template[]

required

Array of template objects.

string

Cursor for the next page. Absent or null on the last page.

GET /v1/templates/

Gets a template by alias or template ID. Because aliases are mutable, reading a template and then creating a sandbox from it can observe different artifacts if the alias is re-pointed between the two calls. The artifact_id on the sandbox record always reflects what was actually used.

curl https://api.example.com/v1/templates/node-tools \
  -H "X-API-Key: <your-api-key>"

Path parameters

string

required

A template alias (e.g. node-tools) or a template ID (NanoID).

Response — 200 OK

string

required

24-character NanoID for this template record.

string

The mutable alias pointing at the current artifact, if one is set.

string

required

The immutable sha256:... digest the alias currently resolves to.

string

Optional human-readable description.

object

Compute shape defined by this template.

Show resources fields

integer

Virtual CPUs.

integer

Memory in mebibytes.

string

required

ISO 8601 timestamp.

Error codes: 401 unauthenticated · 404 not found

DELETE /v1/templates/

Deletes the template record and its alias. The underlying artifact bytes are released by the garbage collector once nothing else references them. Existing sandboxes already created from the artifact continue to run unaffected.

curl -X DELETE https://api.example.com/v1/templates/node-tools \
  -H "X-API-Key: <your-api-key>"

Path parameters

string

required

A template alias or template ID.

Response — 204 No Content Error codes: 401 unauthenticated · 404 not found · 409 template is referenced by an in-progress build

Overview

Control Plane

Data Plane

Templates API: Build and Manage Sandbox Templates

POST /v1/templates/builds

GET /v1/templates/builds/

GET /v1/templates/builds//logs

GET /v1/templates

GET /v1/templates/

DELETE /v1/templates/

​POST /v1/templates/builds

​GET /v1/templates/builds/

​GET /v1/templates/builds//logs

​GET /v1/templates

​GET /v1/templates/

​DELETE /v1/templates/

POST /v1/templates/builds

GET /v1/templates/builds/

GET /v1/templates/builds//logs

GET /v1/templates

GET /v1/templates/

DELETE /v1/templates/