Admin
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.
POST
/
project
/
preview
/
{projectId}
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>",
"auth": {
"type": "password",
"password": "<string>"
}
}
'import requests
url = "https://api.mintlify.com/v1/project/preview/{projectId}"
payload = {
"branch": "<string>",
"auth": {
"type": "password",
"password": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({branch: '<string>', auth: {type: 'password', password: '<string>'}})
};
fetch('https://api.mintlify.com/v1/project/preview/{projectId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mintlify.com/v1/project/preview/{projectId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'branch' => '<string>',
'auth' => [
'type' => 'password',
'password' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mintlify.com/v1/project/preview/{projectId}"
payload := strings.NewReader("{\n \"branch\": \"<string>\",\n \"auth\": {\n \"type\": \"password\",\n \"password\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mintlify.com/v1/project/preview/{projectId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"branch\": \"<string>\",\n \"auth\": {\n \"type\": \"password\",\n \"password\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mintlify.com/v1/project/preview/{projectId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"branch\": \"<string>\",\n \"auth\": {\n \"type\": \"password\",\n \"password\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"statusId": "<string>",
"previewUrl": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"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
Setting
statusId that you can pass to Get deployment status to track the deployment progress.
Branch requirements
Thebranch must exist in the repository connected to your Mintlify project and you must have the Mintlify GitHub App installed. This endpoint does not support branches on forks. See 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
By default, previews created with this endpoint are publicly accessible unless you enable authentication for your previews. See Restrict access to preview deployments. To restrict access to a specific preview, pass anauth object in the request body. Mintlify applies the access setting to the preview before queuing the deployment. If you omit auth, the preview keeps its current access settings.
{ "type": "password", "password": "..." }: Anyone with the password can view the preview. Passwords must be at least 8 characters. Setting a password replaces any existing password on the preview.{ "type": "mintlify" }: Only members of your organization signed in to Mintlify can view the preview.
curl --request POST \
--url https://api.mintlify.com/v1/project/preview/{projectId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"branch": "feature/new-guide",
"auth": { "type": "password", "password": "review-pass-123" }
}'
auth has these requirements:
- Your plan must include preview deployment authentication. Otherwise, the endpoint returns a
403. - Your site must have authentication or preview authentication enabled. Otherwise, the endpoint returns a
409. - Authentication must be enabled on the preview itself. Otherwise, the endpoint returns a
409.
Rate limits
This endpoint allows up to 5 requests per minute per organization.Authorizations
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 in your dashboard.
Path Parameters
Body
application/json
The name of the Git branch to create a preview deployment for.
Minimum string length:
1Access restriction to apply to the preview. Omit to leave the preview's current access settings unchanged. Requires a plan that includes preview authentication, and your site must have authentication or preview authentication enabled.
- Password
- Dashboard login
Show child attributes
Show child attributes
Response
Preview deployment queued successfully.
The status ID for tracking the preview deployment. Use this with the Get deployment status endpoint.
The URL where the preview deployment is hosted.
⌘I
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>",
"auth": {
"type": "password",
"password": "<string>"
}
}
'import requests
url = "https://api.mintlify.com/v1/project/preview/{projectId}"
payload = {
"branch": "<string>",
"auth": {
"type": "password",
"password": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({branch: '<string>', auth: {type: 'password', password: '<string>'}})
};
fetch('https://api.mintlify.com/v1/project/preview/{projectId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mintlify.com/v1/project/preview/{projectId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'branch' => '<string>',
'auth' => [
'type' => 'password',
'password' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mintlify.com/v1/project/preview/{projectId}"
payload := strings.NewReader("{\n \"branch\": \"<string>\",\n \"auth\": {\n \"type\": \"password\",\n \"password\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mintlify.com/v1/project/preview/{projectId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"branch\": \"<string>\",\n \"auth\": {\n \"type\": \"password\",\n \"password\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mintlify.com/v1/project/preview/{projectId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"branch\": \"<string>\",\n \"auth\": {\n \"type\": \"password\",\n \"password\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"statusId": "<string>",
"previewUrl": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}