Reference
View as MarkdownTemplates API
8 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes
/catalog/templatesList the one-click template catalog
Built-in, reviewed templates. q matches every word in the name, summary, tags, licence and database engines (best match first); category and license filter. Source-available templates carry licenseClass: source-available.
| Parameter | In | Type | Description |
|---|---|---|---|
q | query | string | Search terms (name, summary, tags) |
category | query | enum: homelab | media | storage | games | devtools | ai | data | web | analytics | automation | productivity | security | Restrict to a category |
license | query | string | Restrict to a licence class: permissive, copyleft, source-available or proprietary |
Response 200 · OK · application/json
- TemplateCategory[] | nullrequired
- TemplateSummary[] | nullrequired
401Unauthorized403Forbidden422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/catalog/templates/{templateId}Get a template
| Parameter | In | Type | Description |
|---|---|---|---|
templateIdrequired | path | string |
Response 200 · OK · application/json
- categorystringrequired
- descriptionstring
- groupstring
- heavyboolean
- iconstring
- idstringrequired
- TemplateInput[] | nullrequired
- TemplateLinksrequired
- namestringrequired
- notesstring[] | nullrequired
- TemplateOrigin
- TemplateRequiresrequired
- requiresUnrestrictedboolean
- revisioninteger (int64)required
- schemainteger (int64)required
- TemplateService[] | nullrequired
- summarystringrequired
- tagsstring[] | nullrequired
- TemplateUpstreamrequired
401Unauthorized403Forbidden404Not Found422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/environments/{environmentId}/template-instancesList the template stacks installed in an environment
| Parameter | In | Type | Description |
|---|---|---|---|
environmentIdrequired | path | string |
Response 200 · OK · application/json
- createdAtstring (date-time)required
- currentRevisioninteger (int64)required
- currentVersionstringrequired
- environmentIdstringrequired
- groupIdstringrequired
- idstringrequired
- map of stringrequired
- namestringrequired
- TemplateInstanceService[] | nullrequired
- templateIdstringrequired
- templateRevisioninteger (int64)required
- templateVersionstringrequired
- updateAvailablebooleanrequired
- updateBlockedstring
- updatedAtstring (date-time)
401Unauthorized403Forbidden404Not Found422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/environments/{environmentId}/templates/{templateId}/instancesInstall a template
Creates the template's services, volumes, files, variables (secrets generated once), domain, published ports, links and a canvas group as staged changes. With deploy: true the new services are deployed in dependency order (needs deployments:write); templates that publish TCP/UDP ports also need proxy:write.
| Parameter | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | Client-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours. |
environmentIdrequired | path | string | |
templateIdrequired | path | string |
Request body · application/json · required
- deployboolean
- map of string
- namestring
- serverIdstringrequired
Response 201 · Created · application/json
- DeploymentView[] | nullrequired
- TemplateInstancerequired
- ServiceView[] | nullrequired
- warningsstring[] | nullrequired
401Unauthorized403Forbidden404Not Found409Conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/environments/{environmentId}/templates/{templateId}/planPreflight a template install
Returns the services that would be created, the secrets that would be generated (names only) and checks against the chosen server (architecture, memory, proxy, domain, published ports). Nothing is written.
| Parameter | In | Type | Description |
|---|---|---|---|
environmentIdrequired | path | string | |
templateIdrequired | path | string |
Request body · application/json · required
- map of string
- serverIdstring
Response 200 · OK · application/json
- TemplatePlanCheck[] | nullrequired
- TemplatePlanInput[] | nullrequired
- installablebooleanrequired
- proxyRestartbooleanrequired
- secretsstring[] | nullrequired
- TemplatePlanService[] | nullrequired
- TemplateSummaryrequired
- warningsstring[] | nullrequired
401Unauthorized403Forbidden404Not Found422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/template-instances/{instanceId}Delete a template stack
Removes every service of the stack. Requires confirm=<template id>. Volumes are kept unless deleteVolumes=true.
| Parameter | In | Type | Description |
|---|---|---|---|
instanceIdrequired | path | string | |
confirm | query | string | Must equal the template id |
deleteVolumes | query | boolean | Also remove the stack's Docker volumes (data is lost) |
Response 204 · No Content
No body.
401Unauthorized403Forbidden404Not Found409Conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/template-instances/{instanceId}/updateDiff an installed stack against the template's current revision
Lists what changed between the template as installed and the catalog's current revision: apply changes the update would stage, kept ones that differ because you changed the service, manual ones (new or removed services, database upgrades, published ports) that an update never does. Nothing is written. blocked is set for stacks installed before updates existed.
| Parameter | In | Type | Description |
|---|---|---|---|
instanceIdrequired | path | string |
Response 200 · OK · application/json
- appliedinteger (int64)required
- applyinteger (int64)required
- availablebooleanrequired
- blockedstring
- TemplateUpdateChange[] | nullrequired
- currentRevisioninteger (int64)required
- currentVersionstringrequired
- TemplatePlanInput[] | nullrequired
- installedRevisioninteger (int64)required
- installedVersionstringrequired
- instanceIdstringrequired
- keptinteger (int64)required
- manualinteger (int64)required
- namestringrequired
- notesstring[] | nullrequired
- templateIdstringrequired
401Unauthorized403Forbidden404Not Found422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/template-instances/{instanceId}/updateStage a template update
Stages the apply changes of the diff as ordinary edits of the stack's services (image, configuration, variables, files, volumes); nothing is deployed, the staged bar and Deploy do that. Fields you changed are kept, secrets are never overwritten, and databases, routes and services are never touched. revision must be the revision you reviewed (409 template_changed otherwise). A retry after a failure is safe.
| Parameter | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | Client-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours. |
instanceIdrequired | path | string |
Request body · application/json · required
- map of string
- revisioninteger (int64)required
Response 200 · OK · application/json
- TemplateUpdateChange[] | nullrequired
- TemplateInstancerequired
- servicesstring[] | nullrequired
- stagedinteger (int64)required
- warningsstring[] | nullrequired
401Unauthorized403Forbidden404Not Found409Conflicttemplate_changed422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.