> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.manicule.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://mintlify.manicule.dev/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://mintlify.manicule.dev/api/mcp.
> Every agent surface: https://mintlify.manicule.dev/.well-known/llms-manifest.json

# Trigger preview deployment (/api/preview/trigger)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 921 · updated: 2026-07-31 -->
Related: [Trigger deployment](/api/update/trigger.md), [Trigger automation](/api/automations/trigger.md)

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.

`POST /project/preview/{projectId}`

> 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.
>
> Authenticate with an admin API key.

Base URL: `https://api.mintlify.com/v1`

## OpenAPI

```json
{
  "servers": [
    {
      "url": "https://api.mintlify.com/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "securitySchemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer",
      "description": "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."
    }
  },
  "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"
              }
            }
          }
        }
      }
    }
  }
}
```