# Trigger preview deployment

POST

/

project

/

preview

/

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>"
}
'
```

:::code-group
```title="202"
{
  "statusId": "<string>",
  "previewUrl": "<string>"
}
```

```title="400"
{
  "error": "<string>"
}
```

```title="403"
{
  "error": "<string>"
}
```
:::

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](/guides/admin-update-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](/guides/manage-your-site-deploy-preview-deployments#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](/guides/manage-your-site-deploy-preview-deployments#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](https://app.mintlify.com/settings/organization/api-keys) in your dashboard.

#### Path Parameters

projectId

string

required

Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/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](/guides/admin-update-status) endpoint.

previewUrl

string

The URL where the preview deployment is hosted.

⌘I

## Related pages

- [Admin](./admin-index.md)
- [Agent](./agent-2-index.md)
- [Agent](./agent-index.md)
- [Agent-ready content](./agent-ready-content-index.md)
- [AI](./ai-index.md)
- [Analytics](./analytics-index.md)
- [API docs](./api-docs-index.md)
- [API reference](./api-reference-index.md)
- [Assistant](./assistant-2-index.md)
- [Assistant](./assistant-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.