Skip to main content
POST
Trigger preview deployment
Use this endpoint to programmatically create or update a preview deployment for a Git branch. If a preview already exists for the specified branch, the endpoint triggers a redeployment instead of creating a duplicate. The response includes a statusId that you can pass to Get deployment status to track the deployment progress.

Branch requirements

The branch must exist in the repository connected to your Mintlify project and you must have the Mintlify GitHub App installed. Branches on forks are not supported. See Fork pull requests for how to preview changes from a fork.

Use cases

  • CI/CD pipelines: Automatically create preview deployments when users open or update pull requests.
  • Scheduled previews: Build previews from long-running feature branches on a schedule.
  • Custom tooling: Integrate preview creation into internal workflows or Slack bots.

Access to previews

Previews created with this endpoint are publicly accessible unless you enable authentication for your previews, which applies to every preview in your deployment. You cannot password-protect an individual preview through this endpoint. See Restrict access to preview deployments.

Rate limits

This endpoint allows up to 5 requests per minute per organization.

Authorizations

Authorization
string
header
required

The Authorization header expects a Bearer token. Use an admin API key. This is a server-side secret key. Generate one on the API keys page in your dashboard.

Path Parameters

projectId
string
required

Your project ID. Can be copied from the API keys page in your dashboard.

Body

application/json
branch
string
required

The name of the Git branch to create a preview deployment for.

Minimum string length: 1

Response

Preview deployment queued successfully.

statusId
string

The status ID for tracking the preview deployment. Use this with the Get deployment status endpoint.

previewUrl
string

The URL where the preview deployment is hosted.