Templates API

The Templates API provides access to the template catalog for listing, searching, and deploying templates.

List Templates

GET /api/templates

Returns all available templates from the catalog.

Query Parameters:

Parameter	Description
category	Filter by category: ai, databases, devtools, webapps
featured	Filter featured templates: true, false
search	Search by template name or description
sort	Sort by: name, category, featured

Request:

curl https://panel.example.com/api/templates?category=ai \
  -H "Authorization: Bearer aap_k1_..."

Response: 200 OK

{
  "data": [
    {
      "id": "ollama",
      "name": "Ollama",
      "description": "Local LLM inference server — run models on your hardware",
      "category": "ai",
      "featured": true,
      "logo": "/api/templates/ollama/logo",
      "security_profile": "advanced",
      "min_resources": {
        "cpu": 2.0,
        "memory_mb": 4096,
        "storage_mb": 10240
      }
    },
    {
      "id": "librechat",
      "name": "LibreChat",
      "description": "Multi-provider AI chat interface",
      "category": "ai",
      "featured": true,
      "logo": "/api/templates/librechat/logo",
      "security_profile": "secure",
      "min_resources": {
        "cpu": 1.0,
        "memory_mb": 1024,
        "storage_mb": 2048
      }
    }
  ],
  "total": 23
}

Get Template Detail

GET /api/templates/:id

Returns complete details for a single template, including its configurable variables.

Request:

curl https://panel.example.com/api/templates/uptime-kuma \
  -H "Authorization: Bearer aap_k1_..."

Response: 200 OK

{
  "id": "uptime-kuma",
  "name": "Uptime Kuma",
  "description": "Self-hosted monitoring tool",
  "category": "devtools",
  "featured": false,
  "logo": "/api/templates/uptime-kuma/logo",
  "security_profile": "secure",
  "min_resources": {
    "cpu": 0.5,
    "memory_mb": 256,
    "storage_mb": 1024
  },
  "healthcheck": {
    "path": "/",
    "port": 3001,
    "interval": "30s",
    "timeout": "10s"
  },
  "expose": {
    "port": 3001,
    "protocol": "http"
  },
  "variables": [
    {
      "name": "SERVICE_NAME",
      "label": "Service Name",
      "type": "string",
      "required": true,
      "description": "Unique name for the service (becomes the subdomain)"
    }
  ]
}

Variable Schema

Each variable in the variables array has:

Field	Type	Description
name	string	Variable identifier used in compose substitution
label	string	Human-readable label for the form field
type	string	Input type: string, password, number, select, boolean
required	boolean	Whether the variable must be provided
default	any	Default value (used if not provided)
description	string	Help text shown in the form
options	array	Available choices (for select type only)
validation	object	Validation rules (min, max, pattern)

Get Template Logo

GET /api/templates/:id/logo

Returns the SVG logo for a template.

Request:

curl https://panel.example.com/api/templates/uptime-kuma/logo

Response: 200 OK with Content-Type: image/svg+xml

The logo is served from the embedded template catalog. No authentication required.

Deploy from Template

Use the Services API to deploy a template:

POST /api/services

curl -X POST https://panel.example.com/api/services \
  -H "Authorization: Bearer aap_k1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-monitor",
    "customer_id": "cust_def456",
    "deploy_method": "template",
    "template_id": "uptime-kuma",
    "variables": {
      "SERVICE_NAME": "my-monitor"
    }
  }'

Request Body:

Field	Required	Description
name	Yes	Service name (must be unique, becomes subdomain)
customer_id	Yes	Customer who owns the service
deploy_method	Yes	Must be "template"
template_id	Yes	Template ID from the catalog
variables	Yes	Object with variable values matching the template's variable definitions

Response: 201 Created

{
  "id": "svc_new789",
  "name": "my-monitor",
  "status": "deploying",
  "url": "https://my-monitor.panel.example.com",
  "deploy_job_id": "job_xyz456"
}

Variable Validation

The API validates submitted variables against the template's variable definitions:

• Required variables must be present
• Types must match (e.g., number variables must be numeric)
• Values must pass validation rules (min/max, pattern)
• Unknown variables are ignored

If validation fails, the response is 422 Unprocessable Entity:

{
  "error": {
    "code": "validation_error",
    "message": "Template variable validation failed",
    "fields": {
      "SERVICE_NAME": "Service name is required"
    }
  }
}

Template Categories

GET /api/templates/categories

Returns the list of template categories with counts.

Request:

curl https://panel.example.com/api/templates/categories \
  -H "Authorization: Bearer aap_k1_..."

Response: 200 OK

{
  "categories": [
    { "id": "ai", "name": "AI Services", "count": 23 },
    { "id": "databases", "name": "Databases", "count": 5 },
    { "id": "devtools", "name": "DevTools", "count": 7 },
    { "id": "webapps", "name": "Web Apps", "count": 10 }
  ],
  "total": 45
}