Template API

Template Concepts

Templates in ScaleBox are pre-configured environment definitions that serve as the foundation for creating sandbox environments. They define the base image, default resource allocations, and metadata that will be used when users create new sandboxes.

Template Components

• Base Image - Harbor registry image with pre-installed software and configurations
• Resource Defaults - Default CPU, memory, and storage allocations for sandboxes
• Metadata - JSON metadata describing template capabilities and use cases
• Access Control - Public/private visibility and ownership permissions

Template Name Validation

Template names are validated strictly so they work as identifiers (e.g. in sandbox creation and image paths). The same rules apply when creating or updating a template and when providing new_name for share.

• Length: 4–32 characters
• Characters: Only lowercase letters (a–z), numbers (0–9), hyphens (-), and underscores (_)
• Start and end: Must start and end with an alphanumeric character (letter or digit)
• Cannot start with a number
• No consecutive separators: No --, __, -_, or _-
• Cannot start with tpl- (reserved for system template IDs)
• Reserved words (exact match, case-insensitive): admin, root, system, scalebox, harbor, docker, k8s, kubernetes, api, www, mail, ftp, ssh, public, private, test, dev, prod, staging, local, localhost, example, sample

Invalid examples: My Nginx (uppercase and space), nginx (too short), tpl-my-app (reserved prefix), my--app (consecutive hyphens)

Valid examples: my-nginx, python-data-science, node_web_app

Template Statuses

Templates progress through different statuses during their lifecycle:

Template Access Control

Template access is controlled by ownership and visibility settings:

API Endpoints

List Templates

GET /v1/templates

List all accessible templates for the authenticated user.

Request Parameters

Example

curl -X GET https://api.scalebox.dev/v1/templates \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"

Get Template

GET /v1/templates/{template_id}

Get detailed information about a specific template.

Example

curl -X GET https://api.scalebox.dev/v1/templates/tpl-abc123def456789 \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"

Create Template

POST /v1/templates

Create a new template (ScaleBox-family or custom). Full validation applies: name uniqueness, budget, subscription limits, and for custom external images pre-validation.

Request Parameters

Example

curl -X POST https://api.scalebox.dev/v1/templates \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "python-data-science",
    "description": "Python environment with data science libraries",
    "default_cpu_count": 2,
    "default_memory_mb": 4096,
    "harbor_project": "scalebox-public",
    "harbor_repository": "python-data-science",
    "harbor_tag": "latest",
    "metadata": {
      "category": "data-science",
      "languages": ["python"],
      "frameworks": ["pandas", "numpy", "scikit-learn"]
    }
  }'

Update Template

PUT /v1/templates/{template_id}

Update template configuration and Harbor information.

Example

curl -X PUT https://api.scalebox.dev/v1/templates/tpl-abc123def456789 \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated Python environment with latest libraries",
    "default_memory_mb": 8192
  }'

Delete Template

DELETE /v1/templates/{template_id}

Delete a template and its Harbor image.

Example

curl -X DELETE https://api.scalebox.dev/v1/templates/tpl-abc123def456789 \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"

Register Template

POST /v1/templates/register

Register an existing Harbor image as a template. Use when the image already exists in Harbor (e.g. after CLI build/push). Creates a private, scalebox_family template only.

Request Parameters

Example

curl -X POST https://api.scalebox.dev/v1/templates/register \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "existing-image-template",
    "description": "Template for existing Harbor image",
    "harbor_project": "my-project",
    "harbor_repository": "my-app",
    "harbor_tag": "v1.0.0"
  }'

Update Template Status

PUT /v1/templates/{template_id}/status

Update template build status and tracking information.

Request Parameters

Validate Template

POST /v1/templates/{template_id}/validate

Validate and activate a template with Harbor image.

Request Parameters

Get Storage Usage

GET /v1/templates/storage-usage

Get private template storage usage statistics.

Example

curl -X GET https://api.scalebox.dev/v1/templates/storage-usage \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"

Response

{
  "used_gb": 2.5,
  "limit_gb": 5.0,
  "percentage": 50.0
}

List Import Jobs

GET /v1/import-jobs

List template import jobs for the current user.

Request Parameters

Get Import Job

GET /v1/import-jobs/{job_id}

Get a single import job by job ID.

Share Template

POST /v1/templates/{template_id}/share

Share a private template with your account (visibility → account_shared). Only template owner or admin.

Request Parameters

Example

curl -X POST https://api.scalebox.dev/v1/templates/tpl-abc123def456789/share \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{}'

Unshare Template

POST /v1/templates/{template_id}/unshare

Make an account-shared template private again. Only template owner or admin.

Example

curl -X POST https://api.scalebox.dev/v1/templates/tpl-abc123def456789/unshare \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{}'

Create vs Register

Harbor Integration

Templates are tightly integrated with Harbor container registry for image storage and management:

Harbor Project Structure

• Public Templates: Stored in scalebox-public project
• Private Templates: Stored in user-specific projects like scalebox-{user_id}
• Admin Templates: Can be stored in any project, including scalebox-public

Image Management

• Automatic Size Detection: Template image sizes are automatically retrieved from Harbor
• Storage Tracking: Private template storage usage is tracked and limited
• Cleanup: Deleting templates automatically removes Harbor images and repositories

Error Handling

Best Practices

HTTP Status Codes