> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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](https://docs.vertracloud.app/api-reference/endpoint/templates/deploy-status.md) or its [event stream](https://docs.vertracloud.app/api-reference/endpoint/templates/deploy-events.md). The body is the same as [using a catalog template](https://docs.vertracloud.app/api-reference/endpoint/templates/deploy.md), 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](https://docs.vertracloud.app/api-reference/endpoint/templates/share-links/copy.md). 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](https://docs.vertracloud.app/api-reference/endpoint/templates/share-links/preview.md). The applications created from a link can later be reported by their owner and offer updates only while the link is alive.

**token** `string` *required*

The token of the link.

**Idempotency-Key** `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.

**name** `string` *required*

The name of the application, or of the stack when the template has more than one service.

**description** `string`

The description.

**inputs** `object`

The answers to the questions of the template, by question id. A value is a string, a number or a boolean.

**services** `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).

**network\_mode** `string`

Only `public` is accepted. Any other value fails with `STACK_NETWORK_MODE_UNAVAILABLE`.

**workspace\_id** `string`

The workspace that will own what is created.

**folder\_id** `string`

The folder to put the application or stack in.

```bash cURL theme={null}
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

**response** `object`

The job.

**Toggle object**

**id** `string`

The job ID.

**kind** `string`

`deploy` here.

**template\_id** `string`

The template.

**version\_id** `string`

The version being deployed.

**version** `string`

That version number.

**status** `string`

`queued`, `running`, `undoing`, `succeeded` or `failed`.

**current\_step** `string | null`

The step running now, or `null` when the job is queued or finished.

**steps** `object[]`

Each step with its `step`, `status` (`pending`, `running`, `done`, `skipped` or `failed`), `started_at` and `finished_at`.

**error** `object | null`

Set when the job failed: `code`, `message`, `step` and optional `details`.

**resources** `object[]`

What the job created, each with `resource_type`, `resource_id`, `service_id` and `name`. Empty after a failure.

**stack\_id** `string | null`

The stack, when the template has two or more services.

**application\_id** `string | null`

The application, when the template has a single application.

**outputs** `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.

**created\_at** `string`

When the job was created.

**updated\_at** `string`

When the job last changed.

**finished\_at** `string | null`

When the job finished, or `null`.

```json Response theme={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

**code** `string`

The error code indicating the reason for the failure. Possible values:

* `API_KEY_SCOPE_DENIED`: The API key does not have the `templates:deploy` scope (`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 reached `max_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.reason` says 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.

```json Error Response theme={null}
{
  "code": "TEMPLATE_RAM_INSUFFICIENT",
  "details": { "reason": "ram", "required": 512, "available": 256 }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.