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

# Usar un enlace para compartir plantilla para crear aplicaciones

> Crea las aplicaciones, bases de datos y el stack de un enlace de uso como un trabajo asíncrono, seguro de repetir con una Idempotency-Key.

Esta llamada crea, como una sola operación, todo lo que describe la plantilla detrás de un enlace `use`, y responde `202` con un trabajo en `status: "queued"`. Si algún paso falla, se elimina todo lo que creó el trabajo. Sigue el trabajo con [Obtener trabajo de despliegue](https://docs.vertracloud.app/es-es/api-reference/endpoint/templates/deploy-status.md) o con su [flujo de eventos](https://docs.vertracloud.app/es-es/api-reference/endpoint/templates/deploy-events.md). El cuerpo es el mismo que [usar una plantilla del catálogo](https://docs.vertracloud.app/es-es/api-reference/endpoint/templates/deploy.md), sin la elección de versión: el enlace da una sola versión.

Necesita una cuenta (una sesión o una clave de API con el ámbito `templates:deploy`), y solo el propietario de un workspace puede usar una plantilla en él; un miembro recibe `WORKSPACE_OWNER_ONLY`. Un enlace `full_copy` se rechaza aquí con `400`: usa [Copiar plantilla desde un enlace](https://docs.vertracloud.app/es-es/api-reference/endpoint/templates/share-links/copy.md). Cada llamada usa uno de los usos del enlace; una llamada que no termina en un trabajo nuevo devuelve el uso, y también lo devuelve un trabajo que se deshace. Previsualiza primero el enlace con [Previsualizar enlace](https://docs.vertracloud.app/es-es/api-reference/endpoint/templates/share-links/preview.md). Las aplicaciones creadas desde un enlace pueden ser reportadas después por su propietario, y solo ofrecen actualizaciones mientras el enlace siga vigente.

**token** `string` *required*

El token del enlace.

**Idempotency-Key** `string`

Hace la llamada segura de repetir: la misma clave con la misma petición devuelve el mismo trabajo (`200`) y no gasta un segundo uso, y la misma clave con una petición distinta devuelve `IDEMPOTENCY_KEY_CONFLICT`. Se recomienda en cada llamada.

**name** `string` *required*

El nombre de la aplicación, o del stack cuando la plantilla tiene más de un servicio.

**description** `string`

La descripción.

**inputs** `object`

Las respuestas a las preguntas de la plantilla, por ID de pregunta. Un valor es un string, un número o un booleano.

**services** `object`

Elecciones por servicio, por ID de servicio. Cada una puede tener `name`, `ram` (MB, dentro de lo que permite la plantilla) y `subdomain` (`"random"` o el que quieras, para una aplicación con web).

**network\_mode** `string`

Solo se acepta `public`. Cualquier otro valor falla con `STACK_NETWORK_MODE_UNAVAILABLE`.

**workspace\_id** `string`

El workspace que será propietario de lo creado.

**folder\_id** `string`

La carpeta donde poner la aplicación o el 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": "..." } }'
```

### Respuesta

**response** `object`

El trabajo.

**Mostrar objeto**

**id** `string`

El ID del trabajo.

**kind** `string`

`deploy` aquí.

**template\_id** `string`

La plantilla.

**version\_id** `string`

La versión que se despliega.

**version** `string`

Ese número de versión.

**status** `string`

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

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

El paso que se ejecuta ahora, o `null` cuando el trabajo está en cola o ya terminó.

**steps** `object[]`

Cada paso con su `step`, `status` (`pending`, `running`, `done`, `skipped` o `failed`), `started_at` y `finished_at`.

**error** `object | null`

Se define cuando el trabajo falló: `code`, `message`, `step` y `details` opcional.

**resources** `object[]`

Lo que creó el trabajo, cada uno con `resource_type`, `resource_id`, `service_id` y `name`. Vacío tras un fallo.

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

El stack, cuando la plantilla tiene dos o más servicios.

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

La aplicación, cuando la plantilla tiene una sola aplicación.

**outputs** `object[]`

Lo que la plantilla muestra al final, cada una con `label`, `value`, `secret` y `once`. Un valor `once` vuelve solo en la primera lectura del trabajo terminado.

**created\_at** `string`

Cuándo se creó el trabajo.

**updated\_at** `string`

Cuándo cambió el trabajo por última vez.

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

Cuándo terminó el trabajo, o `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
  }
}
```

### Respuestas de error

**code** `string`

El código de error que indica el motivo del fallo. Valores posibles:

* `API_KEY_SCOPE_DENIED`: La clave de API no tiene el ámbito `templates:deploy` (`403`).
* `SHARE_LINK_NOT_FOUND`: El token tiene un formato no válido, no existe, o su plantilla fue eliminada (`404`).
* `SHARE_LINK_REVOKED`, `SHARE_LINK_EXPIRED`, `SHARE_LINK_EXHAUSTED`: El enlace fue revocado, caducó o alcanzó su `max_uses` (`410`).
* `TEMPLATE_INPUT_INVALID`: Falta una respuesta o no es válida.
* `TEMPLATE_PLAN_REQUIRED`: El plan de la cuenta no cubre la plantilla (`403`); `details.reason` indica por qué.
* `TEMPLATE_RAM_INSUFFICIENT`: No hay memoria libre suficiente para la plantilla (`400`).
* `TEMPLATE_IMAGE_SLOTS_EXHAUSTED`: La plantilla necesita más slots de imagen personalizados de los que la cuenta tiene libres (`403`).
* `TEMPLATE_DEPLOY_IN_PROGRESS`: Otro despliegue de la cuenta está en curso (`409`).
* `IDEMPOTENCY_KEY_CONFLICT`: La clave se usó con una petición distinta.
* `MAX_APPS_REACHED`, `MAX_DATABASES_REACHED`: Se superaría el límite del plan.
* `WORKSPACE_OWNER_ONLY`: Solo el propietario de un workspace usa plantillas en él.
* `DEPLOY_RATE_LIMITED`: Demasiados despliegues en la ú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.