Skip to main content

​
Overview

Preview deployments allow you to automatically deploy your application for each pull request or branch, making it easy to test changes before merging to production. Each preview deployment has its own isolated environment and URL.

​
Endpoints

​
List Preview Deployments

Retrieve all preview deployments for a specific application. 
curl -X GET "https://your-dokploy-instance.com/api/previewDeployment.all?applicationId=app_abc123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Query Parameters

​
applicationId
string
required
The unique identifier of the application to retrieve preview deployments for.

​
Response

Returns an array of preview deployment objects.
​
previewDeploymentId
string
Unique identifier for the preview deployment.
​
applicationId
string
Parent application ID.
​
branch
string
Git branch name for this preview deployment.
​
pullRequestNumber
number
Pull request number (if applicable).
​
domain
string
Preview deployment URL.
​
status
string
Current status: building, running, error, or stopped.
​
createdAt
string
ISO 8601 timestamp of creation.

​
Get Preview Deployment

Retrieve details of a specific preview deployment. 
curl -X GET "https://your-dokploy-instance.com/api/previewDeployment.one?previewDeploymentId=preview_xyz789" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Query Parameters

​
previewDeploymentId
string
required
The unique identifier of the preview deployment to retrieve.

​
Response

Returns the preview deployment object with full details including application information.
​
previewDeploymentId
string
Preview deployment identifier.
​
application
object
Associated application object including environment and project details.
​
branch
string
Git branch name.
​
pullRequestNumber
number
Pull request number.
​
domain
string
Preview deployment domain.
​
domainId
string
Associated domain ID.
​
status
string
Current deployment status.

​
Redeploy Preview

Trigger a rebuild of an existing preview deployment. 
curl -X POST https://your-dokploy-instance.com/api/previewDeployment.redeploy \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "previewDeploymentId": "preview_xyz789",
    "title": "Manual rebuild",
    "description": "Rebuilding after configuration change"
  }'

​
Request Body

​
previewDeploymentId
string
required
The ID of the preview deployment to rebuild.
​
title
string
Optional title for the deployment log. Defaults to “Rebuild Preview Deployment”.
​
description
string
Optional description for the deployment.

​
Response

Returns true if the redeploy was successfully queued.
The redeploy operation is queued and runs asynchronously. Check the deployment status using the deployments API to monitor progress.

​
Delete Preview Deployment

Permanently delete a preview deployment and stop its running containers. 
curl -X POST https://your-dokploy-instance.com/api/previewDeployment.delete \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "previewDeploymentId": "preview_xyz789"
  }'

​
Request Body

​
previewDeploymentId
string
required
The ID of the preview deployment to delete.

​
Response

Returns true if the preview deployment was successfully deleted.
Deleting a preview deployment is permanent. All containers, volumes, and associated resources will be removed.

​
Preview Deployment Configuration

Preview deployments inherit configuration from their parent application but can have specific overrides:

​
Environment Variables

Applications can have separate previewEnv environment variables that are used only for preview deployments.

​
Build Configuration

Preview deployments support custom build arguments and secrets:
  • previewBuildArgs - Build arguments specific to preview environments
  • previewBuildSecrets - Build secrets for preview deployments

​
Domain Configuration

Preview deployments automatically generate unique domains based on:
  • previewWildcard - Domain pattern for preview deployments (e.g., *.preview.example.com)
  • previewPort - Port to expose the preview deployment on
  • previewPath - Optional path prefix for the preview deployment
  • previewHttps - Enable HTTPS for preview deployments
  • previewCertificateType - Certificate type: letsencrypt, none, or custom

​
Access Control

​
GitHub Labels

​
Automatic Preview Deployment

When configured on an application, Dokploy automatically:
  1. Creates a preview deployment when a pull request is opened
  2. Updates the preview when new commits are pushed
  3. Adds a comment to the pull request with the preview URL
  4. Cleans up the preview deployment when the pull request is closed or merged
Preview deployments require the application to be connected to a Git provider (GitHub, GitLab, Bitbucket, or Gitea) with webhook support.