Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Models Tools & Services
Solutions
Organisations Developers Internet Service Providers Managed Service Providers AI-in-a-Box
Resources
Support Documentation Blog Downloads
Company
About Research Careers Investment Opportunities Contact
Log in

Templates Reference

Reusable record sets that can be applied to zones. For the guide, see Templates.

Base path: /api/v1/templates/

GET /api/v1/templates/#

List templates visible to the caller. Includes both system (shared) and tenant-custom templates.

Query parameters:

Param Type Notes
page, page_size integer Standard pagination
template_type string system or custom

Response:

json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "data": [
    {
      "id": "tpl_abc123",
      "name": "google-workspace-mail",
      "description": "MX, SPF, and DMARC for Google Workspace",
      "template_type": "custom",
      "record_count": 4,
      "variable_count": 1,
      "created_at": "2026-03-15T14:00:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 50
}

POST /api/v1/templates/#

Create a custom template or apply an existing one. The endpoint is overloaded — distinguish by payload shape:

  • With records[] and variables[]: creates a template.
  • With template_id and domain_id: applies the template to a domain.

Create#

Request:

json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "name": "basic-web",
  "description": "Web apex with www CNAME",
  "records": [
    {"name": "@", "type": "A", "content": "${web_ip}", "ttl": 300},
    {"name": "www", "type": "CNAME", "content": "${domain}.", "ttl": 300}
  ],
  "variables": [
    {"name": "web_ip", "description": "Public IP", "required": true}
  ]
}

Response: Created template.

Apply#

Request:

json
1
2
3
4
5
{
  "template_id": "tpl_abc123",
  "domain_id": "d_xyz789",
  "variables": {"web_ip": "192.0.2.10"}
}

Response:

json
1
2
3
4
5
6
7
8
{
  "created_records": [
    {"id": "r_1", "name": "example.com", "type": "A", "content": "192.0.2.10"}
  ],
  "skipped_records": [],
  "total_created": 1,
  "total_skipped": 0
}

GET /api/v1/templates/{template_id}#

Get a single template.

Response:

json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "id": "tpl_abc123",
  "name": "basic-web",
  "description": "Web apex with www CNAME",
  "template_type": "custom",
  "records": [...],
  "variables": [...],
  "created_at": "...",
  "updated_at": "..."
}

PATCH /api/v1/templates/{template_id}#

Update a custom template. System templates are read-only.

Request: Partial fields — name, description, records, variables.

Response: Updated template.

DELETE /api/v1/templates/{template_id}#

Delete a custom template.

Response: 204 No Content.

GET /api/v1/templates/variables#

Return built-in variables available in all templates.

Response:

json
1
2
3
4
5
6
7
8
{
  "variables": [
    {"name": "domain", "description": "Zone apex name"},
    {"name": "subdomain", "description": "Subdomain portion"},
    {"name": "tenant_slug", "description": "Tenant slug"},
    {"name": "tenant_name", "description": "Tenant display name"}
  ]
}

GET /api/v1/templates/{template_id}/required-variables#

Return the variables a specific template requires.

Response:

json
1
2
3
4
5
{
  "variables": [
    {"name": "web_ip", "description": "Public IP", "required": true}
  ]
}

POST /api/v1/templates/{template_id}/preview/{domain_id}#

Preview the records that would be created without actually creating them.

Request:

json
1
{"variables": {"web_ip": "192.0.2.10"}}

Response:

json
1
2
3
4
5
{
  "records": [
    {"name": "example.com", "type": "A", "content": "192.0.2.10", "ttl": 300}
  ]
}

Schemas#

Template#

Field Type
id string (UUID)
name string
description string
template_type string (system or custom)
records array of record templates (supports ${var} substitution)
variables array of {name, description, required}
tenant_id string or null (null for system templates)

Error codes#

Status Meaning
400 Malformed template (invalid record, unresolved ${var})
403 Can't modify system template; can't apply without records permission
404 Template or domain not found
409 Template name already exists in tenant
422 Variable value missing or wrong type
Updated 2026-05-17 02:38:20 View source (.md) rev 1