---
title: "Turn dark previews on or off, and set TTL and cap"
method: POST
path: "/platform/deployments/custom/{id}/previews/settings"
tags: ["Platform"]
---

# Turn dark previews on or off, and set TTL and cap

`POST /platform/deployments/custom/{id}/previews/settings`

## Request

- Base URL: `https://api.imprezahost.com/v1`
- URL: `https://api.imprezahost.com/v1/platform/deployments/custom/{id}/previews/settings`
- Auth: API key in header `X-API-Key` and API key in header `X-API-Secret`

With previews on, every push to a branch OTHER than the watched one
gets its own ephemeral `.onion`, and a deleted branch takes its
preview with it — merging a pull request usually deletes the branch,
which makes it the most precise expiry signal there is.

Needs a deployment created from `git_url` with its push webhook
connected: the webhook is how we hear about the branch. Manifest
mode is refused — your compose file pins container names, ports and
volumes, and a second copy on the same box would collide with the
running one.

New previews preserve the parent Dockerfile path and use its current Git
credential at clone time. Rotate credentials on the parent, then redeploy
the preview. Supplied webhook commits are pinned from the first build
(agent 0.6.1+); unavailable revisions fail. Older previews are not migrated.

Basic settings use read scope. Changing previews_inherit_vars requires
deploy scope. New previews inherit no application variables by default.
The selected names apply only when creating a preview; existing previews
retain their own variables. Use separate test credentials for previews.

**Previews run on your VPS, not ours.** `max` is what stops a repo
with forty live branches from exhausting the box. Over the cap the
oldest preview is retired to make room for the newest, because the
branch someone just pushed is the one they are waiting for.

## Path parameters

- `id` string, required

## Request body

- object
  - `previews_enabled` boolean: Turning it off leaves running previews alone until they expire.
  - `previews_inherit_vars` string[]: Explicit variable names to copy into NEW previews; empty means none. Requires deploy scope. Identity, ports and resource variables are reserved. Omit to preserve the list. No values or wildcards.
  - `previews_ttl_hours` integer: Hours a preview lives after the LAST push to its branch. Every push slides it forward.
  - `previews_max` integer

## Response `200`

The stored settings

## Other responses

- `400`: Not a git deployment, or manifest mode

---

[API](https://skmtc.dev/imprezahost/apis/impreza-host-public-api.md) · [All operations](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/revisions/db86511f604f?raw)