Frontends

Create a new frontend deployment

Changed on Oct 7, 2026

Creates and deploys a frontend for the project. If a frontend with the same name already exists in the project, this operation updates that frontend using the uploaded archive and starts a new deployment. A deployment that starts immediately returns status: provisioning, then transitions to active, degraded, or failed. If another deployment is running, the response preserves the frontend's current status and exposes the queued deployment through pending_deployment_id. Existing frontend traffic continues to use an available runtime while the new deployment builds and provisions. Each deployment publishes its own static assets before the runtimes switch to its build, and the live build's assets keep serving until the new deployment is live, so a page loaded mid-deployment resolves its assets whichever build served it. A failed redeploy puts the runtimes back on the build they were running, leaves the frontend active on the previous deployment, and records the attempted deployment as failed. degraded means the runtime remains available but edge synchronization requires recovery; Volcano retries the edge step without rebuilding. Only one deployment may run for a given frontend, while independent frontends and projects can deploy concurrently. For monorepos, provide app_root as a relative path from the uploaded archive root to the Next.js app that should be built. Omit it for single-app archives. Supported frontend environments are Next.js 15.x and 16.x with Node.js 22.x or 24.x. The Node.js runtime is inferred from package.json engines.node; if omitted, Volcano uses Node.js 22.x. The selected Node.js family must also satisfy the installed Next.js package's engines.node constraint. Volcano tests Next 15.5.27 (^18.18.0 || ^19.8.0 || >=20.0.0) and Next 16.4.0 (>=20.9.0). Source archive size is enforced by the API with SOURCE_ARCHIVE_SIZE_LIMIT_MB; the CLI does not apply its own source archive size limit. After the final container images are built, the publish build enforces LAMBDA_TARGET_CONTAINER_SIZE_LIMIT_MB before pushing. This operation is limited by plan-based frontend deployment quotas (FREE_FRONTEND_DEPLOYMENTS, PRO_FRONTEND_DEPLOYMENTS). Each project can contain up to 10,000 frontends regardless of plan.

post/projects/{id}/frontends

Request

Base URL: https://api.volcano.dev
URL: https://api.volcano.dev/projects/{id}/frontends
Auth: one of:
- HTTP bearer
- HTTP bearer

Path parameters

idstring uuid required

Project ID

Response

Existing frontend updated; its deployment was started or queued

variable_scope'all' | 'shared' | 'scoped'

All preserves access to all project variables. Shared includes the project frontend shared-variable list. Scoped includes only explicitly declared variables in builds and runtime. Omission preserves the stored selection.

declared_variablesstring[]

Names selected when variable_scope is scoped. Missing declared values reject deployment. Omission preserves the stored list; an empty list clears it.

idstring uuid required

project_idstring uuid required

namestring required

framework'nextjs' required

app_rootstring

Optional relative POSIX path from the uploaded archive root to the Next.js app that is deployed.

status'provisioning' | 'active' | 'degraded' | 'failed' | 'deleting' required

Frontend lifecycle status. degraded means the regional runtime remains available but edge synchronization exhausted its immediate retries; Volcano retries edge recovery without rebuilding the frontend, and stops once a new deployment is queued or the retry budget runs out, leaving the frontend degraded until the next redeploy. A redeploy that fails over a serving frontend stays active on the previous deployment, so failed means no deployment is serving.

provisioning_started_atstring date-time

Timestamp when the current provisioning phase started

deployed_regionsstring[] required

current_deployment_idstring uuid

Identifier of the latest frontend deployment operation

pending_deployment_idstring uuid

Newest queued deployment that will run after the current operation

site_urlstring

custom_domainstring

Active custom domain hostname when configured

Current custom domain lifecycle status

last_invoked_atstring date-time

created_atstring date-time required

updated_atstring date-time required

Changes

Oct 7, 202623e7875e7c4c Revision changes
- ○
  the endpoint scheme security ProjectAccessToken was added to the API
- ○
  added the new optional request property
- ○
  added the new optional request property
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
Sep 19, 20263a6f365f3f35 Revision changes
- ▲
  added the new path request parameter id
- ▲
  the response's body type changed from no type to object for status
- ▲
  the response's body type changed from no type to object for status
- ▲
  the response's body type changed from no type to object for status
- ▲
  the response's body type changed from no type to object for status
- ▲
  the response's body type changed from no type to object for status
- ▲
  the response's body type changed from no type to object for status
- ▲
  the response's body type changed from no type to object for status
- ▲
  the response's body type changed from no type to object for status
- ▲
  the response's body type changed from no type to object for status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the optional property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status
- ○
  added the required property to the response with the status

Operation history (4 revisions)