Skip to main content
POST
/
templates
Create a template and kick off the first build
curl --request POST \
  --url https://api-staging.superserve.ai/templates \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "my-python-env",
  "build_spec": {
    "from": "python:3.11",
    "steps": [
      {
        "run": "pip install -r requirements.txt",
        "workdir": "/srv/app"
      }
    ],
    "start_cmd": "<string>",
    "ready_cmd": "<string>"
  },
  "vcpu": 1,
  "memory_mib": 1024,
  "disk_mib": 4096
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "team_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "status": "building",
  "vcpu": 123,
  "memory_mib": 123,
  "disk_mib": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "build_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Documentation Index

Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

X-API-Key
string
header
required

Body

application/json
name
string
required

Human-readable name, unique per team. Used as the from_template value when creating sandboxes. Lowercase letters, digits, and . _ / - only; must start and end with a letter or digit. Names starting with superserve/ are reserved for curated system templates and rejected for team-owned templates.

Required string length: 1 - 128
Pattern: ^[a-z0-9]([a-z0-9._/-]*[a-z0-9])?$
Example:

"my-python-env"

build_spec
object
required

Declaration of how to build a template.

vcpu
integer
default:1
Required range: 1 <= x <= 4
memory_mib
integer
default:1024
Required range: 256 <= x <= 4096
disk_mib
integer
default:4096
Required range: 1024 <= x <= 8192

Response

Template created; first build queued

Returned by POST /templates — includes both the new template id and the id of the first build that was queued for it. Clients can immediately open the build-log SSE stream or poll the template for status transitions.

id
string<uuid>
team_id
string<uuid>
name
string
status
enum<string>
Available options:
building,
ready,
failed
vcpu
integer
memory_mib
integer
disk_mib
integer
created_at
string<date-time>
build_id
string<uuid>

ID of the first build. Use it to stream logs or poll status.