Previews Applications

Per-deploy preview URL

POST DEL /v1/applications/{uuid}/deploys/{deploy_uuid}/preview

Give one specific build its own stable, publicly reachable URL without making it the live version. POST enables the preview, DELETE disables it. The preview serves that exact deploy (its immutable bundle) at <deploy-uuid>.<your-plan-domain> — independent of which deploy is currently activated — so you can share a build for review before promoting it with activate.

Preview URLs are a static / fullstack-frontend feature. The build must have reached ready. The URL stays valid until you disable the preview or the deploy's artifacts are pruned by retention.

Response (200 OK)

deploy_id int64

The deploy the preview toggle applied to.

preview_enabled bool

true after POST, false after DELETE.

preview_url string

The public per-deploy URL (empty once disabled).

Errors

404

Deploy not found, or it belongs to another application / account.

Request — enable
curl -X POST \
  "https://api.ngris.com/v1/applications/a1b2c3d4-…/deploys/c2d3e4…/preview" \
  -H "X-API-KEY: <your_api_key>"

Response — 200 OK
{
  "deploy_id": 455,
  "preview_enabled": true,
  "preview_url": "https://c2d3e4a5-….ngris.app"
}

Request — disable
curl -X DELETE \
  "https://api.ngris.com/v1/applications/a1b2c3d4-…/deploys/c2d3e4…/preview" \
  -H "X-API-KEY: <your_api_key>"

Enable branch auto-previews

PUT /v1/applications/{uuid}/git/auto-preview

Opt a git-connected app into automatic branch previews. With it on, a push to any branch other than the deploy branch builds a preview deploy instead of touching production — the preview never becomes the live version. It's off by default. This applies to static and fullstack-frontend apps (a fullstack preview builds only the static frontend; API paths still hit the app's live backend).

Request body

enabled bool required

true to auto-build a preview on every non-deploy-branch push; false to turn it off.

Response (200 OK)

auto_preview bool

The new setting.

Errors

400

Invalid request body.

404

Not a git application (auto-previews require a connected repo).

Each branch's newest preview is kept and older ones for that branch are superseded, up to a per-plan cap (max_preview_deploys). Previews expire on a TTL and are cleaned up automatically. Read the current setting from the webhook info endpoint (auto_preview).

Request
curl -X PUT \
  "https://api.ngris.com/v1/applications/a1b2c3d4-…/git/auto-preview" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

Response — 200 OK
{ "auto_preview": true }

List branch previews

GET /v1/applications/{uuid}/previews

List the app's live branch previews — the latest preview per branch. Each entry carries both a stable branch-alias URL (always points at that branch's newest preview) and the immutable per-deploy URL (that exact build), plus branch, status and expiry. The per-plan cap is returned so a UI can show “3 / 5 previews”.

Response (200 OK)

previews[] array

One object per branch (see fields below).

previews[].deploy_uuid string

The preview build.

previews[].branch string

Source branch.

previews[].status string

Build status (ready, building, …).

previews[].git_sha string

Commit the preview was built from.

previews[].version int

Deploy version number.

previews[].branch_url string

Stable alias — this branch's latest preview.

previews[].preview_url string

Immutable URL for this exact build.

previews[].expires_at timestamp

When the preview is reaped (null if none).

cap int

Max concurrent previews on the account's plan.

Request
curl "https://api.ngris.com/v1/applications/a1b2c3d4-…/previews" \
  -H "X-API-KEY: <your_api_key>"

Response — 200 OK
{
  "previews": [
    {
      "deploy_uuid": "e5f6a7b8-…",
      "branch": "feature/new-nav",
      "status": "ready",
      "git_sha": "9c1a2b3",
      "version": 14,
      "branch_url": "https://feature-new-nav-a1b2c3.ngris.app",
      "preview_url": "https://e5f6a7b8-….ngris.app",
      "expires_at": "2026-08-21T10:00:00Z",
      "created_at": "2026-08-14T10:00:00Z"
    }
  ],
  "cap": 5
}