Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Nettalco/dokploy/llms.txt

Use this file to discover all available pages before exploring further.

The Domains API provides full control over how your services are exposed to the internet. You can attach multiple domains to an application or Compose service, generate wildcard subdomains, manage Let’s Encrypt and custom TLS certificates, set up HTTP-to-HTTPS redirects, protect routes with HTTP Basic Authentication, and open raw TCP or UDP ports. Traefik handles the underlying routing and certificate management.

​
Endpoints

MethodEndpointDescription
POST/domain.createAdd a domain to a service
GET/domain.byApplicationIdList domains for an application
GET/domain.byComposeIdList domains for a Compose stack
POST/domain.generateDomainAuto-generate a subdomain
GET/domain.canGenerateTraefikMeDomainsCheck if wildcard generation is available
POST/domain.updateUpdate a domain record
GET/domain.oneFetch a domain by ID
POST/domain.deleteDelete a domain
POST/domain.validateDomainValidate domain DNS propagation
POST/certificates.createUpload a custom TLS certificate
GET/certificates.oneFetch a certificate by ID
POST/certificates.removeDelete a certificate
GET/certificates.allList all certificates
POST/redirects.createCreate an HTTP redirect rule
GET/redirects.oneFetch a redirect by ID
POST/redirects.deleteDelete a redirect rule
POST/redirects.updateUpdate a redirect rule
POST/security.createAdd a Basic Auth security rule
GET/security.oneFetch a security rule by ID
POST/security.deleteDelete a security rule
POST/security.updateUpdate a security rule
POST/port.createExpose a TCP/UDP port
GET/port.oneFetch a port rule by ID
POST/port.deleteDelete a port rule
POST/port.updateUpdate a port rule

​
Key Endpoints

​
POST /domain.create

Attach a custom domain to an application or Compose service. Traefik will start routing traffic for this domain immediately after creation.
​
host
string
required
The fully qualified domain name (e.g., app.example.com).
​
applicationId
string
ID of the application to attach the domain to. Use either this or composeId.
​
composeId
string
ID of the Compose stack to attach the domain to.
​
path
string
URL path prefix for path-based routing (default: /).
​
port
number
Container port the domain should route to (default: 3000).
​
https
boolean
Enable HTTPS for this domain (default: false).
​
certificateType
string
TLS certificate type: none, letsencrypt, or custom.
​
serviceName
string
For Compose stacks, the specific service name to route to.
​
domainId
string
Unique ID of the created domain record.
curl -X POST 'https://your-instance.com/api/domain.create' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "host": "app.example.com",
    "applicationId": "app_xyz789",
    "port": 3000,
    "https": true,
    "certificateType": "letsencrypt"
  }'

​
POST /domain.generateDomain

Automatically generate a traefik.me-based wildcard subdomain for the service — no DNS configuration required.
​
applicationId
string
ID of the application. Use this or composeId.
​
composeId
string
ID of the Compose stack.
​
domain
string
The generated wildcard domain (e.g., abc123.traefik.me).
curl -X POST 'https://your-instance.com/api/domain.generateDomain' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "applicationId": "app_xyz789"
  }'

​
POST /certificates.create

Upload a custom TLS certificate and private key for use with domains.
​
name
string
required
Display name for the certificate.
​
certificateData
string
required
PEM-encoded certificate chain.
​
privateKey
string
required
PEM-encoded private key.
curl -X POST 'https://your-instance.com/api/certificates.create' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "example.com wildcard",
    "certificateData": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  }'

​
POST /security.create

Add HTTP Basic Authentication to a domain. All requests to the domain will prompt for credentials.
​
applicationId
string
required
ID of the application to protect.
​
username
string
required
Basic auth username.
​
password
string
required
Basic auth password (stored as a hashed credential).
curl -X POST 'https://your-instance.com/api/security.create' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "applicationId": "app_xyz789",
    "username": "admin",
    "password": "s3cur3p4ss"
  }'

​
POST /port.create

Expose a TCP or UDP port on the host to route traffic directly to a container port. Useful for non-HTTP protocols.
​
applicationId
string
required
ID of the application.
​
publishedPort
number
required
Host port to listen on.
​
targetPort
number
required
Container port to forward to.
​
protocol
string
required
Protocol: tcp or udp.
curl -X POST 'https://your-instance.com/api/port.create' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "applicationId": "app_xyz789",
    "publishedPort": 8883,
    "targetPort": 1883,
    "protocol": "tcp"
  }'

​
Notes

Use domain.generateDomain for quick testing without DNS configuration. For production, point your DNS A record to the server IP, then create a domain with certificateType: letsencrypt.
domain.validateDomain checks whether DNS has propagated to the server’s IP before issuing a Let’s Encrypt certificate, reducing failed cert issuance.

Build docs developers (and LLMs) love

Get started for freeTalk to us