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.
Authenticate with an admin API key.
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
Section titled “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
Section titled “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
Section titled “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
Section titled “Rate limits”This endpoint allows up to 5 requests per minute per organization.
OpenAPI
Section titled “OpenAPI”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.
Authenticate with an admin API key.
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.
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.