Add trigger preview deployment API endpoint

api/introduction.mdx

@@ -6,10 +6,11 @@
 
 The Mintlify REST (Representational State Transfer) API enables you to programmatically interact with your documentation, trigger updates, embed AI-powered chat experiences, and export analytics data.
 
 ## Endpoints
 
 - [Trigger update](/api/update/trigger): Trigger an update of your site when desired.
 - [Get update status](/api/update/status): Get the status of an update and other details about your docs.
+- [Trigger preview deployment](/api/preview/trigger): Create or update a preview deployment for a specific branch.
 - [Create agent job](/api/agent/v2/create-agent-job): Create an agent job to automatically edit your documentation.
 - [Get agent job](/api/agent/v2/get-agent-job): Retrieve the details and status of a specific agent job.
 - [Send follow-up message](/api/agent/v2/send-message): Send a follow-up message to an existing agent job.
@@ -28,6 +29,7 @@
 
 - **Automated deployments**: Trigger site updates at set intervals or when events occur with [Trigger update](/api/update/trigger) and [Get update status](/api/update/status).
 - **CI/CD integration**: Update documentation as part of your deployment pipeline when code changes with [Trigger update](/api/update/trigger).
+- **Preview deployments**: Create or update preview deployments programmatically in your CI/CD pipeline with [Trigger preview deployment](/api/preview/trigger).
 - **Custom integrations**: Embed the AI assistant into your product, support portal, or internal tools with [Create assistant message](/api/assistant/create-assistant-message-v2), [Search documentation](/api/assistant/search), and [Get page content](/api/assistant/get-page-content).
 - **Automated editing**: Use agent jobs to programmatically update documentation at scale with [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), and [Send follow-up message](/api/agent/v2/send-message).
 - **Analytics export**: Export feedback, assistant conversations, search analytics, page views, and visitor data for external analysis with [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), [Get assistant caller stats](/api/analytics/assistant-caller-stats), [Get search queries](/api/analytics/searches), [Get page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors).
@@ -40,7 +42,7 @@
 
 ### Admin API key
 
-Use the admin API key to authenticate requests to [Trigger update](/api/update/trigger), [Get update status](/api/update/status), [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), [Send follow-up message](/api/agent/v2/send-message), [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), [Get assistant caller stats](/api/analytics/assistant-caller-stats), [Get search queries](/api/analytics/searches), [Get page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors).
+Use the admin API key to authenticate requests to [Trigger update](/api/update/trigger), [Get update status](/api/update/status), [Trigger preview deployment](/api/preview/trigger), [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), [Send follow-up message](/api/agent/v2/send-message), [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), [Get assistant caller stats](/api/analytics/assistant-caller-stats), [Get search queries](/api/analytics/searches), [Get page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors).
 
 Admin API keys begin with the `mint_` prefix. 
 

api/preview/trigger.mdx

@@ -0,0 +1,24 @@
+---
+title: "Trigger preview deployment"
+description: "Create or update a preview deployment for a specific branch to review documentation changes before merging to production."
+openapi: "/openapi.json POST /project/preview/{projectId}"
+keywords: ["preview", "preview deployment", "branch preview", "staging"]
+---
+
+<Info>
+  Preview deployments are available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=preview-deployments).
+</Info>
+
+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 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.

deploy/preview-deployments.mdx

@@ -14,7 +14,7 @@
 
 ## Create preview deployments
 
 Preview deployments are created automatically through pull requests or manually from your dashboard.
 
 ### Automatic previews
 
@@ -39,12 +39,16 @@
 4. Enter the name of the branch you want to preview.
 5. Select **Create preview**.
 
+### API
+
+You can also create preview deployments programmatically using the [Trigger preview deployment](/api/preview/trigger) API endpoint. This is useful for integrating preview creation into CI/CD pipelines or custom tooling.
+
 ## Redeploy a preview
 
 Redeploy a preview to refresh content or retry after a failed deployment.
 
 1. Select the preview from your [dashboard](https://dashboard.mintlify.com/).
 2. Select **Redeploy**.
 
 <Frame>
   <img src="/images/previews/redeploy-preview-light.png" alt="The Previews menu with the deploy button emphasized by an orange rectangle." className="block dark:hidden" />

docs.json

@@ -362,7 +362,8 @@
                 "icon": "activity",
                 "pages": [
                   "api/update/trigger",
-                  "api/update/status"
+                  "api/update/status",
+                  "api/preview/trigger"
                 ]
               },
               {

openapi.json

@@ -209,6 +209,93 @@
           }
         }
       }
+    },
+    "/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://dashboard.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": {