Templates

The Templates API is used to create and manage sandbox templates. Template builds usually include creating a template build record, uploading build files, starting the build, and querying build status.

Create a Template

Description

Creates a new template and returns build task information that can be started later.

Request Path

POST /v3/templates

Compatible paths:

POST /v2/templates
POST /templates

Request Parameters

Parameters for POST /v3/templates:

Parameter	Type	Required	Description
name	string	No	Template name
cpuCount	integer	No	Default CPU core count for the template. Minimum: 1
memoryMB	integer	No	Default memory size for the template, in MiB. Minimum: 128

Parameters for the compatible POST /templates API:

Parameter	Type	Required	Description
dockerfile	string	Yes	Dockerfile content used to build the template
alias	string	No	Template alias
startCmd	string	No	Start command executed after the template starts
readyCmd	string	No	Readiness check command executed after the template starts
cpuCount	integer	No	Default CPU core count for the template
memoryMB	integer	No	Default memory size for the template, in MiB

Response Fields

Returns 202 Accepted on success, indicating that the build task has been created.

Request Example

curl -X POST "$SUFY_SANDBOX_API_URL/v3/templates" \
  -H "X-API-Key: $SUFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-template",
    "cpuCount": 2,
    "memoryMB": 1024
  }'

Get a Build File Upload URL

Description

Gets an upload URL for a template build file. hash is the content hash of the build layer file. If the server cache already has the file, present in the response is true.

Request Path

GET /templates/{templateID}/files/{hash}

Path Parameters

Parameter	Type	Required	Description
templateID	string	Yes	Template ID
hash	string	Yes	Build file content hash

Response Fields

Field	Type	Description
present	boolean	Whether the file already exists in the cache
url	string	File upload URL. Use it when present is false

Start a Template Build

Description

Starts the build task for the specified template.

Request Path

POST /v2/templates/{templateID}/builds/{buildID}

Compatible path:

POST /templates/{templateID}/builds/{buildID}

Path Parameters

Parameter	Type	Required	Description
templateID	string	Yes	Template ID
buildID	string	Yes	Build ID

Request Parameters

Parameter	Type	Required	Description
fromImage	string	No	Base image to use
fromTemplate	string	No	Base template to use
fromImageRegistry	object	No	Private image registry configuration
force	boolean	No	Whether to force rebuilding and skip cache. Defaults to false
steps	array	No	Build step list
startCmd	string	No	Start command executed after the template starts
readyCmd	string	No	Readiness check command executed after the template starts

Returns 202 Accepted on success.

List Default Templates

Request Path

GET /default-templates

Response Fields

Returns an array of template objects:

Field	Type	Description
templateID	string	Template ID
buildID	string	Most recent successful build ID
cpuCount	integer	CPU core count
memoryMB	integer	Memory size in MiB
diskSizeMB	integer	Disk size in MiB
public	boolean	Whether the template is public
aliases	string[]	Template aliases
createdAt	string	Template creation time
updatedAt	string	Template update time
lastSpawnedAt	string	Most recent usage time
spawnCount	integer	Number of times the template has been used
buildCount	integer	Number of template builds
envdVersion	string	envd version
buildStatus	string	Most recent build status

List Templates

Request Path

GET /templates

Response fields are the same as the default template list.

Get Template Details

Request Path

GET /templates/{templateID}

Request Parameters

Parameter	Type	Required	Description
nextToken	string	No	Pagination cursor for the build list
limit	integer	No	Number of builds per page. Range: 1 to 100. Defaults to 100

Response Fields

Field	Type	Description
templateID	string	Template ID
public	boolean	Whether the template is public
aliases	string[]	Template aliases
createdAt	string	Template creation time
updatedAt	string	Template update time
lastSpawnedAt	string	Most recent usage time
spawnCount	integer	Number of times the template has been used
builds	array	Build list

Update a Template

Request Path

PATCH /templates/{templateID}

Request Parameters

Parameter	Type	Required	Description
public	boolean	No	Whether to make the template public

Returns the updated template information on success.

Rebuild a Template

Request Path

POST /templates/{templateID}

Request Parameters

The parameters are the same as the compatible POST /templates API. Returns 202 Accepted on success.

Delete a Template

Request Path

DELETE /templates/{templateID}

Returns 204 No Content on success.

Query Build Status

Request Path

GET /templates/{templateID}/builds/{buildID}/status

Request Parameters

Parameter	Type	Required	Description
logsOffset	integer	No	Build log start offset
limit	integer	No	Number of log entries to return
level	string	No	Log level filter

Response Fields

Field	Type	Description
templateID	string	Template ID
buildID	string	Build ID
status	string	Build status
reason	string	Build status reason
logs	string[]	Build logs
logEntries	array	Structured build logs

Query Build Logs

Request Path

GET /templates/{templateID}/builds/{buildID}/logs

Request Parameters

Parameter	Type	Required	Description
cursor	integer	No	Log cursor
limit	integer	No	Number of log entries to return
direction	string	No	Log read direction
level	string	No	Log level filter
source	string	No	Log source filter

Response Fields

Field	Type	Description
logs	array	Structured build logs

Get a Template by Alias

Request Path

GET /templates/aliases/{alias}

Path Parameters

Parameter	Type	Required	Description
alias	string	Yes	Template alias

Response Fields

Field	Type	Description
templateID	string	Template ID
public	boolean	Whether the template is public

Request Example

curl -X GET "$SUFY_SANDBOX_API_URL/templates/base" \
  -H "X-API-Key: $SUFY_API_KEY"

Related Documents

• API Overview
• Sandbox Instances