Skip to main content
POST
/
project
/
preview
/
{projectId}
Trigger preview deployment
curl --request POST \
  --url https://api.mintlify.com/v1/project/preview/{projectId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "branch": "<string>"
}
'
{
  "statusId": "<string>",
  "previewUrl": "<string>"
}
Preview deployments are available on Pro and Enterprise plans.
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.

​
Use cases

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

​
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 (prefixed with mint_). 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.