Settings

The Settings API is the control plane for your entire Dokploy instance. It covers system health checks, version management, Traefik configuration, Docker maintenance (prune images, volumes, containers), user and permission management, API key lifecycle, cron schedules, container registry integrations, AI provider setup, and backup destinations. Most administrative tasks your team would perform through the dashboard are available here programmatically.

Endpoints

System & Health

Method	Endpoint	Description
GET	`/settings.health`	Health check — returns OK if the API is reachable
GET	`/settings.getDokployVersion`	Get the running Dokploy version
GET	`/settings.getReleaseTag`	Get the latest available release tag
GET	`/settings.getIp`	Get the server’s public IP address
POST	`/settings.updateServerIp`	Update the stored server IP
GET	`/settings.getWebServerSettings`	Get web server (Traefik) settings
POST	`/settings.reloadServer`	Reload the Dokploy server process
POST	`/settings.reloadTraefik`	Reload the Traefik reverse proxy
POST	`/settings.toggleDashboard`	Enable or disable the Dokploy dashboard
POST	`/settings.getUpdateData`	Check for available updates
POST	`/settings.updateServer`	Trigger a Dokploy self-update
GET	`/settings.getOpenApiDocument`	Download the OpenAPI specification
POST	`/settings.setupGPU`	Configure GPU support for containers
GET	`/settings.checkGPUStatus`	Check GPU availability
GET	`/settings.isCloud`	Whether this instance is cloud-hosted
GET	`/settings.isUserSubscribed`	Check subscription status

Docker Maintenance

Method	Endpoint	Description
POST	`/settings.cleanUnusedImages`	Remove unused Docker images
POST	`/settings.cleanUnusedVolumes`	Remove unused Docker volumes
POST	`/settings.cleanStoppedContainers`	Remove stopped containers
POST	`/settings.cleanDockerBuilder`	Clean Docker build cache
POST	`/settings.cleanDockerPrune`	Run a full Docker system prune
POST	`/settings.cleanAll`	Run all cleanup operations
POST	`/settings.cleanMonitoring`	Clear monitoring data
POST	`/settings.updateDockerCleanup`	Configure automatic Docker cleanup schedule

Traefik Configuration

Method	Endpoint	Description
GET	`/settings.readTraefikConfig`	Read the main Traefik configuration
POST	`/settings.updateTraefikConfig`	Update the main Traefik configuration
GET	`/settings.readWebServerTraefikConfig`	Read the web-server Traefik config
POST	`/settings.updateWebServerTraefikConfig`	Update the web-server Traefik config

Users & Permissions

Method	Endpoint	Description
GET	`/user.all`	List all users
GET	`/user.one`	Fetch a user by ID
GET	`/user.get`	Get the current authenticated user
POST	`/user.update`	Update a user’s profile
POST	`/user.remove`	Remove a user
POST	`/user.assignPermissions`	Assign project permissions to a user
POST	`/user.sendInvitation`	Send an email invitation
GET	`/user.getInvitations`	List pending invitations
POST	`/user.createApiKey`	Create an API key for the authenticated user
POST	`/user.deleteApiKey`	Delete an API key
POST	`/user.generateToken`	Generate a temporary session token

Schedules

Method	Endpoint	Description
POST	`/schedule.create`	Create a cron schedule
POST	`/schedule.update`	Update a schedule
POST	`/schedule.delete`	Delete a schedule
GET	`/schedule.list`	List all schedules
GET	`/schedule.one`	Fetch a schedule by ID
POST	`/schedule.runManually`	Run a schedule immediately

Registries & AI

Method	Endpoint	Description
POST	`/registry.create`	Register a container registry
GET	`/registry.all`	List all registries
GET	`/registry.one`	Fetch a registry by ID
POST	`/registry.update`	Update a registry
POST	`/registry.remove`	Remove a registry
POST	`/registry.testRegistry`	Test registry connectivity
POST	`/ai.create`	Create an AI provider config
POST	`/ai.update`	Update an AI provider
GET	`/ai.getAll`	List all AI providers
GET	`/ai.one`	Fetch an AI provider by ID
POST	`/ai.delete`	Delete an AI provider
POST	`/ai.suggest`	Get an AI-generated Compose suggestion
POST	`/ai.deploy`	Deploy from an AI suggestion
GET	`/ai.getModels`	List available AI models

Destinations

Method	Endpoint	Description
POST	`/destination.create`	Create a backup destination
GET	`/destination.all`	List all backup destinations
GET	`/destination.one`	Fetch a destination by ID
POST	`/destination.update`	Update a destination
POST	`/destination.remove`	Remove a destination
POST	`/destination.testConnection`	Test connection to a destination

Key Endpoints

`GET /settings.health`

Simple health check to verify the API is reachable and authenticated.

curl 'https://your-instance.com/api/settings.health' \
  -H 'x-api-key: YOUR_API_KEY'

`POST /settings.cleanAll`

Run all Docker cleanup operations in a single call — removes unused images, volumes, stopped containers, and clears the build cache.

This operation removes all unused Docker resources. Ensure no stopped containers hold data you intend to restart before calling this endpoint.

curl -X POST 'https://your-instance.com/api/settings.cleanAll' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

`POST /user.createApiKey`

Generate a new API key for the currently authenticated user. The key is returned only once — store it securely.

name

string

required

Descriptive label for the API key (e.g., ci-pipeline).

metadata.organizationId

string

required

The organization the key is scoped to. The authenticated user must be a member.

prefix

string

Optional short string prepended to the key value (e.g., ci_).

expiresIn

number

Time-to-live in seconds. Omit for a non-expiring key.

rateLimitEnabled

boolean

Enable per-key rate limiting.

rateLimitTimeWindow

number

Rate limit window duration in milliseconds.

rateLimitMax

number

Maximum requests allowed within the time window.

remaining

number

Total number of requests allowed before the key is exhausted. Omit for unlimited.

key

string

The generated API key value. Only returned at creation time — store it immediately.

string

Unique ID of the API key record. Use this when deleting the key.

name

string

The label assigned to the key.

curl -X POST 'https://your-instance.com/api/user.createApiKey' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "ci-pipeline",
    "metadata": {
      "organizationId": "org_abc123"
    }
  }'

`POST /destination.create`

name

string

required

Display name for the destination.

provider

string

required

Storage provider: aws, cloudflare, backblaze, or other.

bucket

string

required

Name of the S3 bucket.

region

string

required

AWS region or provider region (e.g., us-east-1).

accessKeyId

string

required

S3 access key ID.

secretAccessKey

string

required

S3 secret access key.

endpoint

string

Custom endpoint URL for non-AWS providers (e.g., Cloudflare R2, MinIO).

curl -X POST 'https://your-instance.com/api/destination.create' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Cloudflare R2 Backups",
    "provider": "cloudflare",
    "bucket": "dokploy-backups",
    "region": "auto",
    "accessKeyId": "your-access-key-id",
    "secretAccessKey": "your-secret-access-key",
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com"
  }'

`POST /schedule.create`

Create a cron-based maintenance or task schedule.

name

string

required

Display name for the schedule.

cronExpression

string

required

Standard cron expression (e.g., 0 0 * * * for daily midnight).

type

string

required

Schedule type: docker-cleanup, backup, or command.

command

string

Shell command to run (required when type is command).

curl -X POST 'https://your-instance.com/api/schedule.create' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "nightly-cleanup",
    "cronExpression": "0 2 * * *",
    "type": "docker-cleanup"
  }'

`POST /registry.create`

name

string

required

Display name for the registry.

registryUrl

string

required

Registry hostname (e.g., registry.example.com or ghcr.io).

username

string

required

Registry username.

password

string

required

Registry password or personal access token.

curl -X POST 'https://your-instance.com/api/registry.create' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "GHCR",
    "registryUrl": "ghcr.io",
    "username": "myusername",
    "password": "ghp_xxxxxxxxxxxx"
  }'

Notes

Set up a recurring schedule for docker-cleanup to automatically free disk space on your servers. A weekly schedule (e.g., 0 3 * * 0) is a good starting point.

After calling user.createApiKey, copy the returned key value immediately — Dokploy stores only a hashed version and cannot show it again.

Overview

Applications & Compose

Databases

Infrastructure

Configuration

Endpoints

System & Health

Docker Maintenance

Traefik Configuration

Users & Permissions

Schedules

Registries & AI

Destinations

Key Endpoints

`GET /settings.health`

`POST /settings.cleanAll`

`POST /user.createApiKey`

`POST /destination.create`

`POST /schedule.create`

`POST /registry.create`

Notes

Build docs developers (and LLMs) love

Overview

Applications & Compose

Databases

Infrastructure

Configuration

Documentation Index

​Endpoints

​System & Health

​Docker Maintenance

​Traefik Configuration

​Users & Permissions

​Schedules

​Registries & AI

​Destinations

​Key Endpoints

​GET /settings.health

​POST /settings.cleanAll

​POST /user.createApiKey

​POST /destination.create

​POST /schedule.create

​POST /registry.create

​Notes

Build docs developers (and LLMs) love

Endpoints

System & Health

Docker Maintenance

Traefik Configuration

Users & Permissions

Schedules

Registries & AI

Destinations

Key Endpoints

`GET /settings.health`

`POST /settings.cleanAll`

`POST /user.createApiKey`

`POST /destination.create`

`POST /schedule.create`

`POST /registry.create`

Notes