> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger preview deployment

> Create or update a preview deployment for a specific branch. If a preview already exists for the branch, it triggers a redeployment. Returns a status ID to track progress and the preview URL.

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](/api/update/status) to track the deployment progress.

## 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.

## Rate limits

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


## OpenAPI

````yaml /openapi.json POST /project/preview/{projectId}
openapi: 3.0.1
info:
  title: Mintlify External API
  description: An API for Mintlify documentation management and resource access.
  version: 1.0.0
servers:
  - url: https://api.mintlify.com/v1
security:
  - bearerAuth: []
paths:
  /project/preview/{projectId}:
    post:
      summary: Trigger preview deployment
      description: >-
        Create or update a preview deployment for a specific branch. If a
        preview already exists for the branch, it triggers a redeployment.
        Returns a status ID to track progress and the preview URL.
      parameters:
        - name: projectId
          in: path
          description: >-
            Your project ID. Can be copied from the [API
            keys](https://app.mintlify.com/settings/organization/api-keys) page
            in your dashboard.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - branch
              properties:
                branch:
                  type: string
                  description: >-
                    The name of the Git branch to create a preview deployment
                    for.
                  minLength: 1
      responses:
        '202':
          description: Preview deployment queued successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusId:
                    type: string
                    description: >-
                      The status ID for tracking the preview deployment. Use
                      this with the [Get deployment status](/api/update/status)
                      endpoint.
                  previewUrl:
                    type: string
                    description: The URL where the preview deployment is hosted.
        '400':
          description: Invalid request. The `branch` field is required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '403':
          description: Preview deployments are not available on your current plan.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        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](https://app.mintlify.com/settings/organization/api-keys) in your
        dashboard.

````

## Related topics

- [Preview deployments](/docs/deploy/preview-deployments.md)
- [Mintlify REST API introduction](/docs/api/introduction.md)
- [Trigger deployment](/docs/api/update/trigger.md)