curl -X POST https://api.vertracloud.app/v1/share/templates/vtpl_EXAMPLE_TOKEN/deploy \
-H "Authorization: Bearer $VERTRA_API_KEY" \
-H "Idempotency-Key: 6f1c2d3e-0000-4000-8000-000000000001" \
-H "Content-Type: application/json" \
-d '{ "name": "support-bot", "inputs": { "discord_token": "..." } }'
{
"response": {
"id": "dep-abc123def456",
"kind": "deploy",
"template_id": "tpl-abc123def456",
"version_id": "tplv-111222333444",
"version": "1.0.0",
"status": "queued",
"current_step": null,
"steps": [],
"error": null,
"resources": [],
"stack_id": null,
"application_id": null,
"outputs": [],
"created_at": "2026-10-27T14:02:00Z",
"updated_at": "2026-10-27T14:02:00Z",
"finished_at": null
}
}
Share links
Use a Template Share Link to Create Applications
Creates the applications, databases and stack of a use-mode share link as one asynchronous job, safe to repeat with an Idempotency-Key.
POST
/
v1
/
share
/
templates
/
{token}
/
deploy
curl -X POST https://api.vertracloud.app/v1/share/templates/vtpl_EXAMPLE_TOKEN/deploy \
-H "Authorization: Bearer $VERTRA_API_KEY" \
-H "Idempotency-Key: 6f1c2d3e-0000-4000-8000-000000000001" \
-H "Content-Type: application/json" \
-d '{ "name": "support-bot", "inputs": { "discord_token": "..." } }'
{
"response": {
"id": "dep-abc123def456",
"kind": "deploy",
"template_id": "tpl-abc123def456",
"version_id": "tplv-111222333444",
"version": "1.0.0",
"status": "queued",
"current_step": null,
"steps": [],
"error": null,
"resources": [],
"stack_id": null,
"application_id": null,
"outputs": [],
"created_at": "2026-10-27T14:02:00Z",
"updated_at": "2026-10-27T14:02:00Z",
"finished_at": null
}
}
This call creates, as one operation, everything the template behind a
use link describes, and answers 202 with a job in status: "queued". If any step fails, everything the job created is removed. Follow the job with Get Template Deploy or its event stream. The body is the same as using a catalog template, without the choice of version: the link gives one version.
It requires an account (a session or an API key with the templates:deploy scope), and only the owner of a workspace can use a template in it; a member gets WORKSPACE_OWNER_ONLY. A full_copy link is refused here with 400: use Copy Template from Link. Each call uses one of the link’s uses; a call that does not end in a new job gives the use back, and so does a job that is undone. Preview the link first with Preview Link. The applications created from a link can later be reported by their owner and offer updates only while the link is alive.
string
required
The token of the link.
string
Makes the call safe to repeat: the same key with the same request returns the same job (
200) and spends no second use, and the same key with a different request returns IDEMPOTENCY_KEY_CONFLICT. Recommended on every call.string
required
The name of the application, or of the stack when the template has more than one service.
string
The description.
object
The answers to the questions of the template, by question id. A value is a string, a number or a boolean.
object
Choices per service, by service id. Each can have
name, ram (MB, within what the template allows) and subdomain ("random" or the one you want, for an application with web).string
Only
public is accepted. Any other value fails with STACK_NETWORK_MODE_UNAVAILABLE.string
The workspace that will own what is created.
string
The folder to put the application or stack in.
curl -X POST https://api.vertracloud.app/v1/share/templates/vtpl_EXAMPLE_TOKEN/deploy \
-H "Authorization: Bearer $VERTRA_API_KEY" \
-H "Idempotency-Key: 6f1c2d3e-0000-4000-8000-000000000001" \
-H "Content-Type: application/json" \
-d '{ "name": "support-bot", "inputs": { "discord_token": "..." } }'
Response
object
The job.
Show Toggle object
Show Toggle object
string
The job ID.
string
deploy here.string
The template.
string
The version being deployed.
string
That version number.
string
queued, running, undoing, succeeded or failed.string | null
The step running now, or
null when the job is queued or finished.object[]
Each step with its
step, status (pending, running, done, skipped or failed), started_at and finished_at.object | null
Set when the job failed:
code, message, step and optional details.object[]
What the job created, each with
resource_type, resource_id, service_id and name. Empty after a failure.string | null
The stack, when the template has two or more services.
string | null
The application, when the template has a single application.
object[]
What the template shows at the end, each with
label, value, secret and once. A once value comes back only on the first read of the finished job.string
When the job was created.
string
When the job last changed.
string | null
When the job finished, or
null.{
"response": {
"id": "dep-abc123def456",
"kind": "deploy",
"template_id": "tpl-abc123def456",
"version_id": "tplv-111222333444",
"version": "1.0.0",
"status": "queued",
"current_step": null,
"steps": [],
"error": null,
"resources": [],
"stack_id": null,
"application_id": null,
"outputs": [],
"created_at": "2026-10-27T14:02:00Z",
"updated_at": "2026-10-27T14:02:00Z",
"finished_at": null
}
}
Error Responses
string
The error code indicating the reason for the failure. Possible values:
API_KEY_SCOPE_DENIED: The API key does not have thetemplates:deployscope (403).SHARE_LINK_NOT_FOUND: The token has the wrong form, does not exist, or its template was deleted (404).SHARE_LINK_REVOKED,SHARE_LINK_EXPIRED,SHARE_LINK_EXHAUSTED: The link was revoked, expired, or reachedmax_uses(410).TEMPLATE_INPUT_INVALID: An answer is missing or invalid.TEMPLATE_PLAN_REQUIRED: The plan of the account does not cover the template (403);details.reasonsays why.TEMPLATE_RAM_INSUFFICIENT: Not enough free memory for the template (400).TEMPLATE_IMAGE_SLOTS_EXHAUSTED: The template needs more custom image slots than the account has free (403).TEMPLATE_DEPLOY_IN_PROGRESS: Another deploy of the account is running (409).IDEMPOTENCY_KEY_CONFLICT: The key was used with a different request.MAX_APPS_REACHED,MAX_DATABASES_REACHED: The plan limit would be exceeded.WORKSPACE_OWNER_ONLY: Only the owner of a workspace uses templates in it.DEPLOY_RATE_LIMITED: Too many deploys in the last hour.
{
"code": "TEMPLATE_RAM_INSUFFICIENT",
"details": { "reason": "ram", "required": 512, "available": 256 }
}
Last modified on October 28, 2026