Skip to main content

​
Create Application

curl -X POST https://your-dokploy-instance.com/api/application.create \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Web App",
    "appName": "my-web-app",
    "description": "Production web application",
    "environmentId": "cm5r8k9p00002xyz",
    "serverId": "cm5r8k9p00003xyz"
  }'

{
  "applicationId": "cm5r8k9p00001xyz",
  "name": "My Web App",
  "appName": "my-web-app",
  "description": "Production web application",
  "environmentId": "cm5r8k9p00002xyz",
  "serverId": "cm5r8k9p00003xyz",
  "sourceType": "github",
  "buildType": "nixpacks",
  "applicationStatus": "idle",
  "replicas": 1,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "refreshToken": "abc123def456",
  "autoDeploy": true,
  "createEnvFile": true,
  "buildPath": "/",
  "dockerContextPath": null,
  "dockerBuildStage": null,
  "cleanCache": false
}
Creates a new application in the specified environment. This is the first step in deploying an application - after creation, you’ll configure source providers, build settings, and deploy.

​
Endpoint

POST /application.create

​
Request Body

​
name
string
required
Display name for the application. This will be shown in the Dokploy dashboard.Example: "My Web App"
​
environmentId
string
required
ID of the environment where the application will be created. The application inherits the environment’s project association.Example: "cm5r8k9p00002xyz"
​
appName
string
Internal application name used for Docker containers and resource naming. Must be unique, contain only lowercase letters, numbers, hyphens, and underscores. Maximum 63 characters.If not provided, a unique name will be automatically generated (e.g., app-xyz123).Pattern: ^[a-z0-9][a-z0-9-_]*[a-z0-9]$Example: "my-web-app"
​
description
string
default:"null"
Optional description of the application. Useful for documenting the application’s purpose.Example: "Production web application for customer portal"
​
serverId
string
default:"null"
ID of the server where the application should be deployed. Required in cloud environments.In self-hosted deployments, applications deploy to the local server if not specified.Example: "cm5r8k9p00003xyz"

​
Response Fields

​
applicationId
string
Unique identifier for the created application. Use this ID in all subsequent API calls.
​
name
string
Display name of the application.
​
appName
string
Internal application name used for Docker containers. Guaranteed to be unique.
​
description
string | null
Application description if provided.
​
environmentId
string
ID of the environment containing this application.
​
serverId
string | null
ID of the server where the application is deployed.
​
sourceType
string
Source provider type. Defaults to "github".Possible values: github, gitlab, bitbucket, gitea, docker, git, drop
​
buildType
string
Build strategy type. Defaults to "nixpacks".Possible values: nixpacks, dockerfile, heroku_buildpacks, paketo_buildpacks, railpack, static
​
applicationStatus
string
Current status of the application. Initially "idle".Possible values: idle, running, done, error
​
replicas
number
Number of application replicas. Defaults to 1.
​
createdAt
string
ISO 8601 timestamp when the application was created.
​
refreshToken
string
Automatically generated token for webhook-based deployments.
​
autoDeploy
boolean
Whether automatic deployments are enabled. Defaults to true.
​
createEnvFile
boolean
Whether to create a .env file from environment variables. Defaults to true.
​
buildPath
string
Path within the repository to build from. Defaults to "/".
​
cleanCache
boolean
Whether to clean build cache on next deployment. Defaults to false.

​
Next Steps

After creating an application, you’ll typically:
  1. Configure a source provider - Set up GitHub, GitLab, Docker registry, or other source
  2. Configure build settings - Choose build type and set build parameters
  3. Set environment variables - Configure runtime environment
  4. Deploy the application - Trigger the first deployment

Configure Source Providers

Set up GitHub, GitLab, or other source providers

Deploy Application

Trigger your first deployment

​
Example: Complete Application Setup

Here’s a complete example showing application creation followed by configuration: 
# 1. Create the application
curl -X POST https://your-dokploy-instance.com/api/application.create \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API",
    "appName": "my-api",
    "environmentId": "cm5r8k9p00002xyz"
  }'

# Response: { "applicationId": "cm5r8k9p00001xyz", ... }

# 2. Configure GitHub provider
curl -X POST https://your-dokploy-instance.com/api/application.saveGithubProvider \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "cm5r8k9p00001xyz",
    "repository": "my-api",
    "owner": "my-org",
    "branch": "main",
    "buildPath": "/",
    "githubId": "cm5r8k9p00004xyz",
    "enableSubmodules": false
  }'

# 3. Set environment variables
curl -X POST https://your-dokploy-instance.com/api/application.saveEnvironment \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "cm5r8k9p00001xyz",
    "env": "NODE_ENV=production\nPORT=3000",
    "createEnvFile": true
  }'

# 4. Deploy
curl -X POST https://your-dokploy-instance.com/api/application.deploy \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "cm5r8k9p00001xyz",
    "title": "Initial deployment",
    "description": "First production deploy"
  }'

​
Notes

The appName field must be unique across your Dokploy instance. If you don’t provide one, it will be automatically generated.
In cloud deployments, you must specify a serverId. The request will fail with UNAUTHORIZED if no server is provided.
Newly created applications start in the idle state. Configure the application’s source, build settings, and environment variables before deploying.