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

# Fazer deploy a partir de um link de uso

> Cria as aplicações, bancos e a stack de um link de uso como um único job assíncrono, seguro para repetir com um Idempotency-Key.

Esta chamada cria, como uma única operação, tudo o que o template por trás de um link `use` descreve, e responde `202` com um job em `status: "queued"`. Se alguma etapa falhar, tudo o que o job criou é removido. Acompanhe o job com [Obter job de deploy de template](https://docs.vertracloud.app/pt-br/api-reference/endpoint/templates/deploy-status.md) ou com o [stream de eventos](https://docs.vertracloud.app/pt-br/api-reference/endpoint/templates/deploy-events.md). O corpo é o mesmo de [usar um template do catálogo](https://docs.vertracloud.app/pt-br/api-reference/endpoint/templates/deploy.md), sem a escolha de versão: o link fornece uma única versão.

Exige uma conta (uma sessão ou uma chave de API com o escopo `templates:deploy`), e só o dono de um workspace pode usar um template nele; um membro recebe `WORKSPACE_OWNER_ONLY`. Um link `full_copy` é recusado aqui com `400`: use [Copiar um template a partir de um link de cópia completa](https://docs.vertracloud.app/pt-br/api-reference/endpoint/templates/share-links/copy.md). Cada chamada usa um dos usos do link; uma chamada que não termina em um novo job devolve o uso, e o mesmo acontece com um job que é desfeito. Visualize o link antes com [Visualizar um link de compartilhamento de template](https://docs.vertracloud.app/pt-br/api-reference/endpoint/templates/share-links/preview.md). As aplicações criadas a partir de um link podem ser denunciadas depois pelo dono, e só recebem atualizações enquanto o link estiver ativo.

**token** `string` *required*

O token do link.

**Idempotency-Key** `string`

Torna a chamada segura para repetir: a mesma chave com a mesma requisição retorna o mesmo job (`200`) e não gasta um segundo uso; a mesma chave com uma requisição diferente retorna `IDEMPOTENCY_KEY_CONFLICT`. Recomendado em todas as chamadas.

**name** `string` *required*

O nome da aplicação, ou da stack quando o template tem mais de um serviço.

**description** `string`

A descrição.

**inputs** `object`

As respostas às perguntas do template, por ID da pergunta. Um valor é um texto, um número ou um booleano.

**services** `object`

Escolhas por serviço, por ID do serviço. Cada um pode ter `name`, `ram` (MB, dentro do que o template permite) e `subdomain` (`"random"` ou o que você quiser, para uma aplicação com web).

**network\_mode** `string`

Só `public` é aceito. Qualquer outro valor falha com `STACK_NETWORK_MODE_UNAVAILABLE`.

**workspace\_id** `string`

O workspace que será dono do que for criado.

**folder\_id** `string`

A pasta onde colocar a aplicação ou a stack.

```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": "..." } }'
```

### Resposta

**response** `object`

O job.

**Mostrar objeto**

**id** `string`

O ID do job.

**kind** `string`

`deploy` neste caso.

**template\_id** `string`

O template.

**version\_id** `string`

A versão que está sendo implantada.

**version** `string`

O número dessa versão.

**status** `string`

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

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

A etapa em execução agora, ou `null` quando o job está na fila ou terminou.

**steps** `object[]`

Cada etapa com seu `step`, `status` (`pending`, `running`, `done`, `skipped` ou `failed`), `started_at` e `finished_at`.

**error** `object | null`

Definido quando o job falhou: `code`, `message`, `step` e `details` opcional.

**resources** `object[]`

O que o job criou, cada item com `resource_type`, `resource_id`, `service_id` e `name`. Vazio após uma falha.

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

A stack, quando o template tem dois ou mais serviços.

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

A aplicação, quando o template tem uma única aplicação.

**outputs** `object[]`

O que o template exibe ao final, cada item com `label`, `value`, `secret` e `once`. Um valor `once` volta apenas na primeira leitura do job finalizado.

**created\_at** `string`

Quando o job foi criado.

**updated\_at** `string`

Quando o job mudou pela última vez.

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

Quando o job terminou, ou `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
  }
}
```

### Respostas de erro

**code** `string`

O código de erro que indica o motivo da falha. Valores possíveis:

* `API_KEY_SCOPE_DENIED`: A chave de API não tem o escopo `templates:deploy` (`403`).
* `SHARE_LINK_NOT_FOUND`: O token tem formato inválido, não existe, ou o template foi excluído (`404`).
* `SHARE_LINK_REVOKED`, `SHARE_LINK_EXPIRED`, `SHARE_LINK_EXHAUSTED`: O link foi revogado, expirou ou atingiu `max_uses` (`410`).
* `TEMPLATE_INPUT_INVALID`: Uma resposta está faltando ou é inválida.
* `TEMPLATE_PLAN_REQUIRED`: O plano da conta não cobre o template (`403`); `details.reason` informa o motivo.
* `TEMPLATE_RAM_INSUFFICIENT`: Memória livre insuficiente para o template (`400`).
* `TEMPLATE_IMAGE_SLOTS_EXHAUSTED`: O template precisa de mais vagas de imagem personalizada do que a conta tem livres (`403`).
* `TEMPLATE_DEPLOY_IN_PROGRESS`: Outro deploy da conta está em execução (`409`).
* `IDEMPOTENCY_KEY_CONFLICT`: A chave foi usada com uma requisição diferente.
* `MAX_APPS_REACHED`, `MAX_DATABASES_REACHED`: O limite do plano seria ultrapassado.
* `WORKSPACE_OWNER_ONLY`: Só o dono de um workspace usa templates nele.
* `DEPLOY_RATE_LIMITED`: Deploys demais na última hora.

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