> ## 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. # Crear aplicación > Crea una aplicación nueva con la configuración y los archivos indicados. La aplicación tiene **dos orígenes mutuamente excluyentes**: envía exactamente uno de `file` o `snapshot_id`. Si no envías ninguno → `SOURCE_REQUIRED`; si envías los dos → `SOURCE_CONFLICT`. **file** `file` El archivo ZIP con el código de la aplicación (tamaño máximo: 100 MB). No se envía cuando el origen es `snapshot_id`. **snapshot\_id** `string` Origen alternativo a `file`: el ID de un snapshot de **aplicación** desde el que crear la aplicación. La plataforma descarga el snapshot (que ya incluye el `vertracloud.config`) y construye la aplicación a partir de él. Se envía como campo de texto del cuerpo multipart; tiene el mismo límite de tamaño que `file` (100 MB). **memory** `string` La cantidad de RAM que se asigna a la aplicación, en MB. Mínimo 100 MB. Es obligatoria con `file`; con `snapshot_id` es opcional y, si no se envía, se usa el `vertracloud.config` del snapshot. Cuando se pide un `subdomain`, el valor sube automáticamente a al menos 512 MB: las aplicaciones web tienen su propio mínimo de memoria. **start** `string` El comando de inicio de la aplicación. **build** `string` Un comando de build opcional, de hasta 512 caracteres (por ejemplo, `npm run build`). Se ejecuta después de instalar las dependencias y antes de que la aplicación arranque, en un entorno de build aislado: 2× la RAM de la aplicación (mínimo 1.024 MB, máximo 4.096 MB) con un tiempo límite de 10 minutos. Las `devDependencies` se instalan cuando hay un comando de build. Disponible en todos los planes. Consulta [Actualizar configuración de la aplicación](https://docs.vertracloud.app/es-es/api-reference/endpoint/apps/updateconfig.md) para cambiarlo más adelante. **main** `string` El archivo principal de la aplicación. Es obligatorio con `file`; con `snapshot_id` es opcional y, si no se envía, se usa el `vertracloud.config` del snapshot. **language** `string` Opcional. Fuerza el lenguaje de ejecución en lugar de detectarlo a partir del proyecto: uno de `javascript`, `typescript`, `bun`, `python`, `static`, `php`, `go`, `ruby`, `java`, `rust`, `deno`, `dotnet`, `elixir`. Precedencia: este campo, después `LANGUAGE=` en `vertracloud.config`, y por último la detección. Cualquier otro valor se rechaza con `INVALID_LANGUAGE`. **version** `string` Obligatoria con `file`; con `snapshot_id` se usa la versión del `vertracloud.config` del snapshot. La versión del runtime de la aplicación: `recommended`, `latest` o una versión concreta soportada por el runtime detectado (por ejemplo, `22`). **name** `string` *required* El nombre visible de la aplicación. Máximo 50 caracteres. **description** `string` Una descripción de la aplicación. **workspace\_id** `string` El ID del workspace que se asocia a la aplicación, si aplica. **subdomain** `string` El subdominio de la aplicación (por ejemplo, `miapp`). Los espacios se reemplazan por `-` y el valor se pasa a minúsculas antes de validarlo; el formato aceptado es `^[a-z0-9-]+$`. Envía `random` para que la plataforma elija uno por ti. Omite el campo por completo para crear una aplicación privada, sin publicación web; más adelante puedes activarla con [Publicar aplicación en la web](https://docs.vertracloud.app/es-es/api-reference/endpoint/apps/network/publish.md). Requiere que el plan admita la publicación web. **envs** `string` Una cadena JSON con un array de variables de entorno, cada una con `key`, `value` y un `note` opcional. Longitud máxima de la clave 255, del valor 3072 y de la nota 50. ### Respuesta La creación es asíncrona: la respuesta es `202 Accepted` con la aplicación en `status: "building"`. Después, consulta los [Detalles de la aplicación](https://docs.vertracloud.app/es-es/api-reference/endpoint/apps/get.md) o los [logs en tiempo real](https://docs.vertracloud.app/es-es/api-reference/endpoint/apps/realtime.md) hasta que `status` sea `up` o `down`. Mientras esté en `building`, iniciar, detener, reiniciar, los despliegues de archivos, el rollback, los snapshots, las restauraciones y los cambios de configuración responden `409 APP_BUILDING`; eliminar la aplicación sí está permitido. Si el build se interrumpe, la aplicación queda en `down` y `BUILD_INTERRUPTED` aparece en sus logs; si la plataforma cancela la creación (por ejemplo, porque la cola está llena), la aplicación deja de existir y los Detalles de la aplicación responden `404`. **response** `object` Los detalles de la aplicación creada. **Mostrar objeto** **id** `string` El ID de la aplicación. **owner\_id** `string` El ID del propietario de la aplicación. **owner\_plan** `string | null` El nombre del plan del propietario (por ejemplo, `pro` o `enterprise-8`), o `null` cuando el propietario no tiene plan. **name** `string` El nombre de la aplicación. **description** `string` La descripción de la aplicación. **cluster** `integer` El ID del clúster de la aplicación. **status** `string` El estado de la aplicación. La creación responde `202 Accepted` con `building`; la instalación y el build continúan en segundo plano. Cuando terminan, el estado pasa a `up`, o a `down` si fallaron la instalación de dependencias o el comando `build` (la salida está en los logs, así que puedes corregir los archivos y volver a iniciar sin subirlos de nuevo). **last\_build\_error** `string | null` El código del último fallo de build o de instalación, o `null` tras un build correcto. Uno de `BUILD_FAILED`, `BUILD_TIMEOUT`, `BUILD_INTERRUPTED`, `INSTALL_FAILED`, `INSTALL_OUT_OF_MEMORY`, `INSTALL_TIMEOUT` o `INSTALL_SHIELD_BLOCKED`. El detalle está en los logs de la aplicación; consulta [Errores](https://docs.vertracloud.app/es-es/api-reference/errors.md#códigos-de-fallo-del-build) para saber qué hacer con cada código. **ram** `integer` La RAM de la aplicación, en MB. **type** `integer` El tipo de aplicación. **language** `string` El lenguaje de programación de la aplicación (por ejemplo, `javascript`, `deno`, `dotnet`, `elixir`). **subdomain** `string | null` El subdominio de la aplicación, si aplica. **domains** `APIApplicationDomain[]` Los dominios personalizados de la aplicación. Siempre está vacío justo después de crearla; añádelos con [Añadir dominio a la aplicación](https://docs.vertracloud.app/es-es/api-reference/endpoint/apps/domains/create.md). **created\_at** `string` La fecha y hora en que se creó la aplicación. **updated\_at** `string` La fecha y hora de la última actualización de la aplicación. **last\_snapshot** `string | null` La fecha y hora del último snapshot de la aplicación. **main\_file** `string` El archivo principal de la aplicación. **version** `string` La versión del runtime (por ejemplo, `recommended` o `latest`). **start\_command** `string | null` El comando de inicio de la aplicación, si se ha indicado. **build\_command** `string | null` El comando de build, si se ha indicado. Se ejecuta después de instalar las dependencias y antes de que la aplicación arranque. **offline\_since** `string | null` La fecha y hora desde la que la aplicación está fuera de línea, si aplica. **shield\_cooldown** `object | null` Presente mientras Vertra Shield ha pausado la aplicación. Incluye `until` (fin de la pausa), `reason` (`burst` o `rate_limit`) y `direction` (`in` o `out`); `null` cuando no hay ninguna pausa activa. **github** `object | null` Repositorio de GitHub vinculado (`repo_owner`, `repo_name`) cuando el despliegue automático está conectado; `null` cuando la aplicación se creó desde un ZIP o un snapshot. La URL del webhook no se incluye: para obtenerla usa `GET /v1/apps/{id}/deploys/webhook`. **custom\_image** `object | null` La imagen Docker personalizada desde la que se ejecuta la aplicación; `null` en una aplicación normal. Con una imagen, `language`, `version`, `main_file`, `start_command` y `build_command` no se aplican: vienen de la imagen. Consulta [Imágenes Docker personalizadas](https://docs.vertracloud.app/es-es/guides/custom-docker-images.md). **Propiedades de custom\_image** **image\_id** `string` El ID de la imagen. `id` y `name` de este objeto son los de la aplicación, no los de la imagen. **port** `integer | null` El puerto en el que escucha la aplicación y al que la plataforma envía el tráfico; `null` para una aplicación sin tráfico web. **version\_id** `string | null` La versión de la imagen que ejecuta la aplicación, o `null` si todavía no se ha iniciado en ninguna versión. **outdated** `boolean` `true` cuando la imagen tiene una versión más nueva que la que ejecuta la aplicación. Pasará a ella en el siguiente reinicio o despliegue que pidas. **deploy** `object` Cómo un despliegue reemplaza la versión en ejecución y qué ocurre si falla. **Propiedades de deploy** **zero\_downtime** `string` La opción guardada: `off` (la predeterminada), `auto` u `on`. Cámbiala con [Actualizar configuración de la aplicación](https://docs.vertracloud.app/es-es/api-reference/endpoint/apps/updateconfig.md). **zero\_downtime\_active** `boolean` Lo que se aplica al siguiente reinicio o despliegue: `true` en Enterprise cuando `zero_downtime` es `on`, o cuando es `auto` y la aplicación recibe tráfico web. **auto\_rollback** `boolean` La opción guardada, `false` por defecto. Devuelve el valor guardado en cualquier plan, pero solo tiene efecto desde Intermediary. **health\_check\_path** `string | null` La ruta HTTP a la que se llama en una versión nueva para comprobar que está sana. `null` significa `/`. **warning** `string` Solo cuando creas desde el snapshot de una aplicación que ejecuta una imagen Docker personalizada y la versión de la imagen registrada en el snapshot ya no existe: `IMAGE_VERSION_NOT_FOUND`. La aplicación se crea con la versión actual de la imagen. ```json Response theme={null} { "response": { "id": "app-abc123def456", "owner_id": "user-123456789012345678", "owner_plan": "pro", "name": "API Simples", "description": "I have a description :)", "cluster": 1, "status": "building", "ram": 128, "type": 2, "language": "javascript", "subdomain": "myapp.vertraweb.app", "domains": [], "last_snapshot": "2026-03-20T19:58:00Z", "main_file": "index.js", "version": "recommended", "start_command": null, "build_command": null, "offline_since": null, "shield_cooldown": null, "github": null, "custom_image": null, "deploy": { "zero_downtime": "off", "zero_downtime_active": false, "auto_rollback": false, "health_check_path": null }, "created_at": "2026-03-20T19:58:00Z", "updated_at": "2026-03-20T19:58:00Z" } } ``` ### Respuestas de error **code** `string` El código de error que indica el motivo del fallo. Valores posibles: * `VALIDATION_ERROR`: El cuerpo multipart no superó la validación (`400`). La respuesta incluye también `message` y `path`, que apuntan al campo con el problema. * `USER_NOT_FOUND`: No se pudo resolver el usuario autenticado (`401`). * `MAX_APPS_REACHED`: Se alcanzó el límite de aplicaciones del plan (`403`). * `INVALID_ZIP`: El archivo subido no es un ZIP legible (truncado o dañado) (`400`). * `MAIN_FILE_NOT_FOUND`: El archivo indicado en `main` no existe dentro del ZIP (`400`). * `ZIP_TOO_SMALL`: El archivo subido pesa menos de 100 bytes (`400`). * `FILE_TOO_LARGE`: El archivo subido supera el límite de 100 MB (`400`). * `SOURCE_REQUIRED`: No se envió ni `file` ni `snapshot_id` (`400`). * `SOURCE_CONFLICT`: Se enviaron `file` y `snapshot_id` a la vez (`400`). * `SNAPSHOT_NOT_FOUND`: El `snapshot_id` no existe o no pertenece a quien hace la llamada (`404`). * `SNAPSHOT_TYPE_MISMATCH`: El snapshot es de una base de datos, no de una aplicación (`400`). * `SNAPSHOT_TOO_LARGE`: El snapshot supera el mismo límite de creación de 100 MB que `file` (`400`). * `MEMORY_REQUIRED`: No se envió `memory` y el `vertracloud.config` del snapshot no tiene un `MEMORY` utilizable (`400`). * `PLAN_REQUIRED`: El propietario no tiene un plan activo, así que no se puede crear una aplicación nueva, o se pidió un `subdomain` sin plan (`403`). * `PLAN_DOES_NOT_SUPPORT_WEB_PUBLISH`: Se pidió un `subdomain`, pero el plan del propietario no incluye la publicación web (`403`). * `INVALID_MEMORY_FORMAT`: `memory` no es un número (`400`). * `MEMORY_MUST_BE_INTEGER`: `memory` no es un entero (`400`). * `MEMORY_BELOW_MINIMUM`: `memory` está por debajo del mínimo para el tipo de aplicación (`400`). * `MEMORY_LIMIT_EXCEEDED`: La memoria pedida supera la que aún tiene disponible el plan (`400`). * `SUBDOMAIN_TAKEN`: Otra aplicación ya usa ese subdominio (`409`). * `SUBDOMAIN_FORBIDDEN`: El subdominio pedido está en la lista de reservados de la plataforma (`400`). * `USER_LIMITS_NOT_FOUND`: No se pudo cargar el registro de límites del propietario (`404`). * `INVALID_LANGUAGE`: El lenguaje no es compatible o no se pudo determinar (`400`). * `DEPLOY_RATE_LIMITED`: Se alcanzó el presupuesto de despliegues por hora del plan de la cuenta (`429`). Consulta la [introducción a la referencia de la API](https://docs.vertracloud.app/es-es/api-reference/introduction.md). * `INTERNAL_SERVER_ERROR`: Error inesperado, incluida una aplicación que se creó pero no se pudo leer después (`500`). **message** `string` Una descripción detallada con información adicional sobre el error. Presente en `VALIDATION_ERROR`. ```json Error Response (400) theme={null} { "code": "VALIDATION_ERROR", "message": "Main file is required", "path": "main" } ``` ```json Error Response (400) theme={null} { "code": "MAIN_FILE_NOT_FOUND" } ``` ```json Error Response (403) theme={null} { "code": "PLAN_REQUIRED" } ``` > [!NOTE] > > Una aplicación creada sin `subdomain` sigue siendo privada. Puedes activar la publicación web más adelante con > [Publicar aplicación en la web](https://docs.vertracloud.app/es-es/api-reference/endpoint/apps/network/publish.md), y desactivarla con la misma ruta. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.