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
}
}
Enlaces para compartir
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.
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
}
}
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 o con su flujo de eventos. El cuerpo es el mismo que usar una plantilla del catálogo, 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. 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. Las aplicaciones creadas desde un enlace pueden ser reportadas después por su propietario, y solo ofrecen actualizaciones mientras el enlace siga vigente.
string
requerido
El token del enlace.
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.string
requerido
El nombre de la aplicación, o del stack cuando la plantilla tiene más de un servicio.
string
La descripción.
object
Las respuestas a las preguntas de la plantilla, por ID de pregunta. Un valor es un string, un número o un booleano.
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).string
Solo se acepta
public. Cualquier otro valor falla con STACK_NETWORK_MODE_UNAVAILABLE.string
El workspace que será propietario de lo creado.
string
La carpeta donde poner la aplicación o el stack.
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
object
El trabajo.
Mostrar Mostrar objeto
Mostrar Mostrar objeto
string
El ID del trabajo.
string
deploy aquí.string
La plantilla.
string
La versión que se despliega.
string
Ese número de versión.
string
queued, running, undoing, succeeded o failed.string | null
El paso que se ejecuta ahora, o
null cuando el trabajo está en cola o ya terminó.object[]
Cada paso con su
step, status (pending, running, done, skipped o failed), started_at y finished_at.object | null
Se define cuando el trabajo falló:
code, message, step y details opcional.object[]
Lo que creó el trabajo, cada uno con
resource_type, resource_id, service_id y name. Vacío tras un fallo.string | null
El stack, cuando la plantilla tiene dos o más servicios.
string | null
La aplicación, cuando la plantilla tiene una sola aplicación.
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.string
Cuándo se creó el trabajo.
string
Cuándo cambió el trabajo por última vez.
string | null
Cuándo terminó el trabajo, o
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
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 ámbitotemplates: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ó sumax_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.reasonindica 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.
{
"code": "TEMPLATE_RAM_INSUFFICIENT",
"details": { "reason": "ram", "required": 512, "available": 256 }
}
Última modificación el 28 de octubre de 2026