Skip to main content
POST
Create Application
The application has two mutually exclusive sources — send exactly one of file or snapshot_id. Neither → SOURCE_REQUIRED; both → SOURCE_CONFLICT.
file
The ZIP file containing the application code (maximum size: 100 MB). Absent when the source is snapshot_id.
string
Alternative source to file: the id of an application snapshot to create the app from. The platform downloads the snapshot (which already carries the vertracloud.config) and builds the app from it. Sent as a text field of the multipart body — same size limit as file (100 MB).
string
The amount of RAM to allocate for the application in MB. Minimum 100 MB. Required with file; with snapshot_id it is optional and falls back to the snapshot’s vertracloud.config. When a subdomain is requested the value is raised to at least 512 MB automatically — web applications have their own memory floor.
string
The application startup command.
string
An optional build command, up to 512 characters (e.g. npm run build). Runs after dependency installation and before the application starts, in an isolated build environment — 2× the application’s RAM (min 1,024 MB, max 4,096 MB) and 2× its vCPU (min 1, max 2), with a 10-minute timeout. Available on every plan. See Update Application Configuration to change it later.
string
The main file of the application. Required with file; with snapshot_id it is optional and falls back to the snapshot’s vertracloud.config.
string
Required with file; with snapshot_id it falls back to the snapshot’s vertracloud.config. The application runtime version: recommended, latest, or a specific version supported by the detected runtime (e.g. 22).
string
required
The application display name. Maximum 50 characters.
string
An application description.
string
The workspace ID to associate with the application, if applicable.
string
The subdomain for the application (e.g., myapp). Whitespace is replaced with - and the value is lowercased before validation; the accepted format is ^[a-z0-9-]+$. Send random to let the platform pick one for you. Omit the field entirely to create a private application with no web publishing — you can turn it on later with Publish Application on the Web.Requires plan support for web publishing.
string
A JSON string containing an array of environment variables, each with key, value and an optional note. Maximum key length 255, maximum value length 3072, maximum note length 50.

Response

object
The details of the created application.

Error Responses

string
The error code indicating the reason for the failure. Possible values:
  • VALIDATION_ERROR: The multipart body failed validation (400). The response also carries message and path pointing at the offending field.
  • USER_NOT_FOUND: The request is not authenticated (403), or the owner’s limits could not be resolved (404).
  • MAX_APPS_REACHED: The plan’s application limit has been reached (403).
  • INVALID_ZIP: The uploaded file is not a readable ZIP (truncated or corrupted) (400).
  • MAIN_FILE_NOT_FOUND: The file named in main does not exist inside the ZIP (400).
  • ZIP_TOO_SMALL: The uploaded file is smaller than 100 bytes (400).
  • FILE_TOO_LARGE: The uploaded file exceeds the 100 MB limit (400).
  • SOURCE_REQUIRED: Neither file nor snapshot_id was sent (400).
  • SOURCE_CONFLICT: Both file and snapshot_id were sent (400).
  • SNAPSHOT_NOT_FOUND: The snapshot_id doesn’t exist or doesn’t belong to the caller (404).
  • SNAPSHOT_TYPE_MISMATCH: The snapshot is a database snapshot, not an application one (400).
  • SNAPSHOT_TOO_LARGE: The snapshot exceeds the same 100 MB creation ceiling as file (400).
  • MEMORY_REQUIRED: memory was omitted and the snapshot’s vertracloud.config has no usable MEMORY (400).
  • FREE_PLAN_SUSPENDED: The owner is on the Free plan, which can’t create new applications (403).
  • FREE_PLAN_NO_WEB_PUBLISH: A subdomain was requested but the owner’s plan does not include web publishing (403).
  • INVALID_MEMORY_FORMAT: memory is not a number (400).
  • MEMORY_MUST_BE_INTEGER: memory is not an integer (400).
  • MEMORY_BELOW_MINIMUM: memory is below the minimum for the application type (400).
  • MEMORY_LIMIT_EXCEEDED: The requested memory exceeds the memory still available on the plan (400).
  • SUBDOMAIN_TAKEN: Another application already uses that subdomain (409).
  • SUBDOMAIN_FORBIDDEN: The requested subdomain is on the platform’s reserved list (400).
  • USER_LIMITS_NOT_FOUND: The owner’s limits record could not be loaded (404).
  • INVALID_LANGUAGE: The application language could not be determined (500).
  • INTERNAL_SERVER_ERROR: The application was created but could not be read back (500).
  • DEPLOY_RATE_LIMITED: The account’s hourly deploy budget for its plan was reached (429). See API Reference Introduction.
  • INTERNAL_SERVER_ERROR: Unexpected failure (500).
string
A descriptive message providing additional details about the error. Present on VALIDATION_ERROR.
An application created without subdomain stays private. You can turn web publishing on later with Publish Application on the Web, and off again with the same route.