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.
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>"
}
'import requests
url = "https://api.mintlify.com/v1/project/preview/{projectId}"
payload = { "branch": "<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>'})
};
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>'
]),
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}")
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}")
.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}"
response = http.request(request)
puts response.read_body{
"statusId": "<string>",
"previewUrl": "<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
statusId that you can pass to Get deployment 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.Authorizations
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 in your dashboard.
Path Parameters
Body
application/json
The name of the Git branch to create a preview deployment for.
Minimum string length:
1Response
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.
Was this page helpful?
⌘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>"
}
'import requests
url = "https://api.mintlify.com/v1/project/preview/{projectId}"
payload = { "branch": "<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>'})
};
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>'
]),
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}")
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}")
.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}"
response = http.request(request)
puts response.read_body{
"statusId": "<string>",
"previewUrl": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}