Template API

Template API

Publish immutable droplet configuration revisions and resolve required deployment inputs.

Templates store reusable droplet configuration without copying running memory or disk contents. A published revision pins image and policy references.

Publish a revision

POST/organizations/{organization_id}/projects/{project_id}/templates
Scope
droplets:write
Auth
Bearer API key

Publishes a template with pinned configuration and required deployment inputs.

Send name and configuration, using the writable droplet creation fields. Fields deliberately supplied by the caller at deployment time belong in required_inputs, an array of supported field paths. The same field cannot be both fixed and required as an input.

To publish a template with required deployment inputs, send:

JSON
{
  "name": "payments-web",
  "configuration": {
    "region_id": "reg_euwest",
    "image_id": "img_ubuntu",
    "vcpus": 2,
    "memory_mib": 4096,
    "root_volume": { "size_gib": 30, "storage_policy_id": "sp_replicated" },
    "labels": { "service": "web" }
  },
  "required_inputs": ["name", "interfaces", "ssh_key_ids"]
}

Returns 201 with template ID and revision ID. Invalid fixed configuration returns 422 and publishes no revision. Network availability and physical capacity are checked again when a droplet is created.

Revise

POST/organizations/{organization_id}/projects/{project_id}/templates/{template_id}/revisions
Scope
droplets:write
Auth
Bearer API key

Publishes an immutable replacement template revision.

Requires droplets:write and the template's current If-Match. It creates a new immutable revision from a complete configuration and required-input set. It does not patch the earlier revision or modify droplets created from it.

GET/organizations/{organization_id}/projects/{project_id}/templates/{template_id}/revisions/{revision_id}
Scope
droplets:read
Auth
Bearer API key

Returns the pinned configuration revision. The caller needs droplets:read and visibility of the project.

Resolve and deploy

POST/organizations/{organization_id}/projects/{project_id}/templates/{template_id}/resolve
Scope
droplets:write
Auth
Bearer API key

Resolves deployment inputs into a validated droplet request without creating resources.

Accepts revision_id and an inputs object. Resolution returns the complete proposed droplet request and validation results without creating resources.

An absent required input returns 422 missing_template_input. Overriding a fixed field returns 422 fixed_template_field. Explicit null does not satisfy a required non-null input.

POST/organizations/{organization_id}/projects/{project_id}/templates/{template_id}/deploy
Scope
droplets:write
Auth
Bearer API key

Deploys a droplet from the selected template revision.

Send the resolved inputs and an idempotency key. It returns the new droplet summary and operation with 202. The result records the template revision used.

Retire

PATCH/organizations/{organization_id}/projects/{project_id}/templates/{template_id}
Scope
droplets:write
Auth
Bearer API key

Updates the template's deprecation state.

Send deprecated=true to hide the template from default selection. Requires If-Match; existing droplets remain unchanged.

DELETE/organizations/{organization_id}/projects/{project_id}/templates/{template_id}
Scope
droplets:write
Auth
Bearer API key

Deletes a template after retained policy references permit removal.

Deletion is blocked while retained policy references require its revisions. Existing droplets retain their recorded revision reference and independent resource lifecycle.

A template is configuration, not a backup. Use cloning or Snapshot API when data must be copied, and blueprints for dependencies spanning several resource types.