Skip to main content
Templates define the blueprint for deployments. They specify container images, resources, environment variables, and secrets. Templates support multiple visibility scopes: private (user-only), team, org, and public.

​
Template Operations

​
List Templates

GET /api/templates
Returns all templates accessible to the authenticated user, including:
  • System templates (available to all users)
  • User’s private templates
  • Templates shared with user’s teams
  • Templates shared with user’s organizations
  • Public templates
Authentication: Required (session or API key with templates:read scope) Response:
​
name
string
Template identifier (URL-safe, unique)
​
displayName
string
Human-readable template name
​
description
string
Template description
​
category
string
Category (e.g., “web”, “database”, “ai”)
​
image
string
Primary container image
​
containerPort
integer
Primary container port
​
cpuRequest
string
CPU request (e.g., “100m”)
​
cpuLimit
string
CPU limit (e.g., “500m”)
​
memoryRequest
string
Memory request (e.g., “128Mi”)
​
memoryLimit
string
Memory limit (e.g., “512Mi”)
​
healthCheckPath
string
HTTP health check path (e.g., “/health”)
​
enabled
boolean
Whether the template is enabled
​
hasConfigMap
boolean
Whether a ConfigMap is synced for this template
​
isSystem
boolean
Whether this is a built-in system template
​
envVars
array
Array of environment variable definitions
​
visibility
string
Visibility scope: private, team, org, or public
​
orgId
string
Organization ID (for org-scoped templates)
​
teamId
string
Team ID (for team-scoped templates)
​
orgName
string
Organization name
​
teamName
string
Team name
​
spec
string
Full YAML specification
Example: 
curl -X GET "https://your-domain.com/api/templates" \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "name": "nginx",
    "displayName": "NGINX Web Server",
    "description": "High-performance HTTP server and reverse proxy",
    "category": "web",
    "image": "nginx:latest",
    "containerPort": 80,
    "cpuRequest": "100m",
    "cpuLimit": "500m",
    "memoryRequest": "128Mi",
    "memoryLimit": "512Mi",
    "healthCheckPath": "/",
    "enabled": true,
    "hasConfigMap": true,
    "isSystem": true,
    "visibility": "public"
  }
]

​
Get Template Details

GET /api/templates/{name}
Retrieve detailed information about a specific template, including full YAML specification. Path Parameters:
​
name
string
required
Template name
Authentication: Required Response: Same fields as list endpoint, plus full spec field with YAML specification. Example: 
curl -X GET "https://your-domain.com/api/templates/nginx" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Create Template

POST /api/templates
Create a new template. Templates are synced to a Kubernetes ConfigMap for use by the operator. Authentication: Required (templates:write scope) Request Body:
​
name
string
required
Template identifier (must be URL-safe, alphanumeric + hyphens)
​
displayName
string
required
Human-readable name
​
description
string
Template description
​
category
string
Category for grouping (e.g., “web”, “database”)
​
image
string
Container image
​
containerPort
integer
Container port (default: 8080)
​
cpuRequest
string
CPU request (default: “100m”)
​
cpuLimit
string
CPU limit (default: “500m”)
​
memoryRequest
string
Memory request (default: “128Mi”)
​
memoryLimit
string
Memory limit (default: “512Mi”)
​
healthCheckPath
string
HTTP health check path (default: ”/”)
​
enabled
boolean
Enable the template (default: true)
​
hasConfigMap
boolean
Whether to sync a ConfigMap
​
envVars
array
Array of environment variable definitions
​
visibility
string
Visibility scope: private, team, org, or public (default: private)
​
orgId
string
Organization ID (required for org visibility)
​
teamId
string
Team ID (required for team visibility)
​
spec
string
Full YAML specification (JSON string)
​
secrets
array
Array of secret definitions (values stored in Vault)
Response: 201 Created Example: 
curl -X POST "https://your-domain.com/api/templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-api",
    "displayName": "My API Service",
    "description": "Custom API service",
    "category": "web",
    "image": "myregistry.com/api:latest",
    "containerPort": 3000,
    "visibility": "private",
    "envVars": [
      {
        "name": "PORT",
        "defaultValue": "3000",
        "description": "HTTP port"
      }
    ]
  }'
Permissions:
  • private visibility: No special permissions required
  • team visibility: Requires team_admin role
  • org visibility: Requires org_owner or org_admin role
  • public visibility: Requires platform_admin role
Notes:
  • Template creation triggers automatic sync to Kubernetes ConfigMap
  • Secret values are stripped from spec and stored separately in Vault
  • If sync fails, template creation is rolled back

​
Update Template

PUT /api/templates/{name}
Update an existing template. System templates cannot be modified. Path Parameters:
​
name
string
required
Template name (cannot be changed)
Request Body: Same fields as create endpoint (except name is ignored). Response: 200 OK Example: 
curl -X PUT "https://your-domain.com/api/templates/my-api" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "My API Service v2",
    "image": "myregistry.com/api:v2.0.0",
    "memoryLimit": "1Gi"
  }'

​
Delete Template

DELETE /api/templates/{name}
Delete a template. System templates cannot be deleted. This also removes the template from the ConfigMap. Path Parameters:
​
name
string
required
Template name
Response: 204 No Content Example: 
curl -X DELETE "https://your-domain.com/api/templates/my-api" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
AI Template Generation

​
Generate Template with AI

POST /api/templates/generate
Generate a deployment template using AI (Claude) based on a natural language prompt. The AI uses the user’s organization context for personalized results. Authentication: Required (templates:write scope) Request Body:
​
prompt
string
required
Natural language description of the desired template (e.g., “Create a PostgreSQL database with persistent storage”)
Response:
​
name
string
Generated template name
​
displayName
string
Human-readable name
​
description
string
Template description
​
category
string
Template category
​
yaml
string
Full YAML specification
Example: 
curl -X POST "https://your-domain.com/api/templates/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a Redis cache with 2GB memory limit and persistence enabled"
  }'

{
  "name": "redis-cache",
  "displayName": "Redis Cache",
  "description": "Redis in-memory cache with persistence",
  "category": "database",
  "yaml": "services:\n  - name: redis\n    image: redis:7-alpine\n    containerPort: 6379\n    resources:\n      requests:\n        cpu: 100m\n        memory: 256Mi\n      limits:\n        cpu: 500m\n        memory: 2Gi\n    volumes:\n      - name: data\n        mountPath: /data\n        size: 10Gi"
}
Notes:
  • AI generation can take 15-30 seconds
  • Requires Anthropic API key in server configuration
  • Generated template is automatically saved to the database
  • Uses organization’s aiContext field for personalized results
  • If template name already exists, it’s updated instead of creating a duplicate
Requirements:
AI template generation requires ANTHROPIC_API_KEY to be configured on the server. If not configured, this endpoint returns 503 Service Unavailable.

​
Template Specification Format

Templates use a YAML-based specification format that defines services, resources, volumes, and secrets: 
services:
  - name: nginx
    image: nginx:latest
    containerPort: 80
    healthCheckPath: /
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
      limits:
        cpu: 500m
        memory: 512Mi
    env:
      - name: PORT
        value: "80"
    secrets:
      - key: API_KEY
        description: "External API key"
    volumes:
      - name: config
        mountPath: /etc/nginx/conf.d
        configMap: nginx-config

​
Services

Each service defines a container:
​
name
string
required
Service name (used in DNS)
​
image
string
required
Container image
​
containerPort
integer
required
Port the container listens on
​
healthCheckPath
string
HTTP health check path
​
resources
object
CPU and memory requests/limits
​
env
array
Environment variables
​
secrets
array
Secret references (values in Vault)
​
volumes
array
Volume mounts

​
Environment Variables

Environment variables can be defined at deployment time: 
{
  "name": "PORT",
  "defaultValue": "8080",
  "description": "HTTP server port",
  "required": false
}

​
Secrets

Secrets are defined in templates but values are stored in Vault: 
{
  "key": "DATABASE_PASSWORD",
  "description": "PostgreSQL password",
  "serviceName": "postgres"
}
See Secrets API for managing secret values.

​
Template Visibility Scopes

Templates support four visibility levels:

​
Private

Visible only to the creating user. 
{
  "visibility": "private"
}

​
Team

Visible to all members of a specific team. 
{
  "visibility": "team",
  "teamId": "team_123abc"
}

​
Organization

Visible to all members of an organization. 
{
  "visibility": "org",
  "orgId": "org_456def"
}

​
Public

Visible to all users (system templates). 
{
  "visibility": "public"
}

​
Error Responses

​
error
string
Human-readable error message

​
Common Error Codes

  • 400 Bad Request - Invalid template name or spec format
  • 403 Forbidden - Insufficient permissions for visibility scope or attempting to modify system template
  • 404 Not Found - Template not found or not accessible
  • 409 Conflict - Template name already exists
  • 500 Internal Server Error - ConfigMap sync failed or database error
  • 503 Service Unavailable - Template storage not configured or AI generation unavailable

Build docs developers (and LLMs) love

Get started for freeTalk to us