Deploy through the API

Create a release from a project branch, wait for its preparation, and assign it to a specific environment through REST.

Before you start

Use Bash, curl, and jq. If combining these commands into a script, start it with set -euo pipefail so it stops after an error. The project must already contain the source to release, and the target environment must have its required configuration and runtime capacity.

Use an API key with release and deployment permissions. Replace the placeholders and select the branch and environment intentionally:

bash
export VERYFRONT_API_KEY="<API_KEY>"
export VERYFRONT_PROJECT="<PROJECT_SLUG_OR_ID>"
BRANCH_REFERENCE="main"
ENVIRONMENT_NAME="staging"
API_BASE="${VERYFRONT_API_URL:-https://api.veryfront.com}"

Steps

  1. Resolve the target environment ID.
  2. Create a release from the selected branch and keep its returned ID.
  3. Check export and build completion before requesting deployment.
  4. Verify the deployment record and the application behavior.

Try it with REST

GET /projects/{project_reference}/environments

bash
curl --silent --show-error --fail-with-body \
  "$API_BASE/projects/$VERYFRONT_PROJECT/environments?limit=100" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -o environments.json

ENVIRONMENT_ID=$(jq -er --arg name "$ENVIRONMENT_NAME" \
  '[.data[] | select(.name == $name)] | if length == 1 then .[0].id else error("Expected one target environment") end' \
  environments.json)

If the environment isn't returned, check its name and the response's pagination. Create or configure the environment before continuing. Naming a release “staging” doesn't select a staging target.

POST /projects/{project_reference}/releases

bash
curl --silent --show-error --fail-with-body \
  "$API_BASE/projects/$VERYFRONT_PROJECT/releases" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg branch "$BRANCH_REFERENCE" \
    '{name: "API deployment", branch_reference: $branch}')" \
  -o release.json

RELEASE_ID=$(jq -er '.id' release.json)

GET /projects/{project_reference}/releases/{release_id}

bash
curl --silent --show-error --fail-with-body \
  "$API_BASE/projects/$VERYFRONT_PROJECT/releases/$RELEASE_ID" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -o release-status.json

jq '{id, version, export_status, build_status, asset_manifest}' release-status.json
jq -e '.export_status == "completed" and .build_status == "completed"' \
  release-status.json

Repeat this GET while preparation is in_progress. Continue only when the check returns true. For error, a failed asset manifest, or a stage with no recorded status, inspect release details and logs before proceeding.

POST /projects/{project_reference}/deployments

bash
curl --silent --show-error --fail-with-body \
  "$API_BASE/projects/$VERYFRONT_PROJECT/deployments" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg release "$RELEASE_ID" --arg environment "$ENVIRONMENT_ID" \
    '{release_id: $release, environment_id: $environment}')" \
  -o deployment.json

DEPLOYMENT_ID=$(jq -er '.id' deployment.json)

Verify

GET /projects/{project_reference}/deployments/{deployment_id}

bash
curl --silent --show-error --fail-with-body \
  "$API_BASE/projects/$VERYFRONT_PROJECT/deployments/$DEPLOYMENT_ID" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -o deployment-status.json

jq -e --arg release "$RELEASE_ID" --arg environment "$ENVIRONMENT_ID" \
  '.release_id == $release and .environment_id == $environment' \
  deployment-status.json

This confirms the release/environment assignment, not application correctness. In Studio's Environments panel, confirm the environment's current deployment and open its domain.

Repeat a request that exercises the released change. For a protected environment, follow Cloud environment access. An access challenge isn't necessarily a deployment failure.

Use Logs for runtime errors and Traces for an agent or tool failure. A later deployment to the same environment can replace the version you assigned.

API reference