Skip to main content

​
Overview

Projects in Dokploy are the top-level organizational unit that contain environments and services. Each project can have multiple environments (e.g., production, staging, development) with their own applications, databases, and compose services.

​
Create Project

Create a new project in your organization.
​
name
string
required
The name of the project.
​
description
string
Optional description of the project.
​
env
string
Project-level environment variables (KEY=VALUE format, one per line).

​
Response

​
project
object
The created project object.
​
environment
object
The default environment created with the project.
cURL
curl -X POST "https://your-dokploy-instance.com/api/project.create" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Application",
    "description": "Production application for e-commerce platform"
  }'

​
Get Project

Retrieve details about a specific project including all environments and services.
​
projectId
string
required
The unique identifier of the project.

​
Response

Returns the project with nested environments containing applications, databases (postgres, mysql, mariadb, mongo, redis), and compose services.
cURL
curl -X GET "https://your-dokploy-instance.com/api/project.one?projectId=project-123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
List All Projects

Get all projects in your organization.

​
Response

Returns an array of projects with their environments and service summaries.
cURL
curl -X GET "https://your-dokploy-instance.com/api/project.all" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Update Project

Update project configuration.
​
projectId
string
required
The ID of the project to update.
​
name
string
New project name.
​
description
string
New project description.
​
env
string
Project-level environment variables.
cURL
curl -X POST "https://your-dokploy-instance.com/api/project.update" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project-123",
    "name": "Updated Project Name",
    "description": "Updated description"
  }'

​
Delete Project

Delete a project and all its environments and services.
​
projectId
string
required
The ID of the project to delete.
This action is irreversible and will delete all environments, applications, databases, and compose services within the project.
cURL
curl -X POST "https://your-dokploy-instance.com/api/project.remove" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project-123"
  }'

​
Duplicate Project

Create a copy of an environment, optionally including services.
​
sourceEnvironmentId
string
required
The environment ID to duplicate from.
​
name
string
required
Name for the new project or environment.
​
description
string
Description for the duplicated project.
​
includeServices
boolean
default:true
Whether to copy services from the source environment.
​
selectedServices
array
Specific services to duplicate. If not provided, all services are copied.Each service object contains:
  • id (string) - The service ID
  • type (string) - One of: application, postgres, mariadb, mongo, mysql, redis, compose
​
duplicateInSameProject
boolean
default:false
If true, creates a new environment in the same project. If false, creates a new project.
cURL
curl -X POST "https://your-dokploy-instance.com/api/project.duplicate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceEnvironmentId": "env-123",
    "name": "Staging Clone",
    "description": "Cloned from production",
    "includeServices": true,
    "duplicateInSameProject": true
  }'

​
Search Projects

Search and filter projects in your organization.
​
q
string
General search query (searches name and description).
​
name
string
Filter by project name (partial match).
​
description
string
Filter by description (partial match).
​
limit
number
default:20
Number of results to return (1-100).
​
offset
number
default:0
Number of results to skip for pagination.

​
Response

​
items
array
Array of matching projects.
​
total
number
Total count of matching projects.
cURL
curl -X GET "https://your-dokploy-instance.com/api/project.search?q=ecommerce&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Project Structure

A typical project structure in Dokploy: 
Project
├── Environment: Production
│   ├── Applications
│   ├── Databases (Postgres, MySQL, etc.)
│   └── Compose Services
├── Environment: Staging
│   ├── Applications
│   └── Databases
└── Environment: Development
    └── Applications

​
Environment Variables

Project-level environment variables are inherited by all services within the project. You can override them at the environment or service level. Format environment variables as: 
DATABASE_URL=postgresql://localhost:5432/mydb
REDIS_URL=redis://localhost:6379
API_KEY=your_api_key_here

Build docs developers (and LLMs) love

Get started for freeTalk to us