REST API

By default, the API is enabled and exposed on port 3000. You can override this behaviour using environment variables.

API Versioning

Starting in v1.4.0, the canonical API base path is /api/v1/*. The unversioned /api/* path was a backward-compatible alias during migration; it was removed in v1.6.0.

The four whitelisted wud-card compatibility endpoints keep responding at /api/* when DD_COMPAT_WUDCARD=true (three reshaped into a bare-array shape, the fourth unmodified), served by their own router rather than by falling through to the removed alias. Two standalone auth aliases, GET /api/auth/methods and GET /api/auth/status, are also unaffected — unconditionally, not behind any flag — because both are registered directly on the app rather than through the removed alias router; see Authentication routes below. Everything else under /api/* now returns 410 Gone; use /api/v1/*. See Deprecations for details.

Error Contract

All error responses (HTTP 4xx/5xx) return a consistent JSON structure:

{
  "error": "Container not found"
}

Authentication

When authentication is enabled, all API endpoints require a valid session (cookie-based via Basic or OIDC login). For cross-domain OIDC providers, keep DD_SERVER_COOKIE_SAMESITE=lax (default) unless you have a specific same-site policy requirement.

The webhook endpoints use a separate Bearer token authentication.

Destructive action confirmation

Some destructive endpoints require an explicit confirmation header:

X-DD-Confirm-Action: <token>

If the header is missing or does not match the expected token, the API responds with 428 Precondition Required.

Endpoint overview

Additional endpoints

Command endpoint convention

Some endpoints are intentional action commands and use POST under a resource path (for example container watch/scan/reveal). These are RPC-style operations rather than CRUD updates.

Registry webhook

POST /api/v1/webhooks/registry receives registry-provider webhook payloads and immediately checks matching containers.

The endpoint does not use the regular webhook bearer token. It requires an HMAC-SHA256 signature computed with DD_SERVER_WEBHOOK_SECRET. Drydock accepts sha256=<hex> or raw hex signatures from these headers:

• x-drydock-signature
• x-hub-signature-256
• x-quay-signature
• x-harbor-signature
• x-ms-signature
• x-registry-signature

payload='{"provider":"dockerhub","repository":"library/nginx"}'
signature="sha256=$(printf '%s' "$payload" | openssl dgst -sha256 -hmac "$DD_SERVER_WEBHOOK_SECRET" -binary | xxd -p -c 256)"

curl -X POST http://drydock:3000/api/v1/webhooks/registry \
  -H "Content-Type: application/json" \
  -H "x-drydock-signature: $signature" \
  -d "$payload"

Returns 202 Accepted with registry dispatch counts, 401 for a missing or invalid signature, 403 when registry webhooks are disabled, 429 when rate-limited, or 500 if the endpoint is enabled without a configured secret.

Notification rules

Notification rules control which events trigger notifications, which triggers receive them, the in-app bell filters, and optional per-provider message templates. Seven default rules are created automatically.

Get all notification rules

curl http://drydock:3000/api/v1/notifications

{
  "data": [
    {
      "id": "update-available",
      "name": "Update Available",
      "description": "When a container has a new version",
      "enabled": true,
      "triggers": [],
      "bellEnabled": true,
      "bellThreshold": "all",
      "templates": {}
    },
    {
      "id": "update-applied",
      "name": "Update Applied",
      "description": "After a container is successfully updated",
      "enabled": true,
      "triggers": [],
      "bellEnabled": true,
      "bellThreshold": "all",
      "templates": {}
    },
    {
      "id": "update-failed",
      "name": "Update Failed",
      "description": "When an update fails or is rolled back",
      "enabled": true,
      "triggers": [],
      "bellEnabled": true,
      "bellThreshold": "all",
      "templates": {}
    },
    {
      "id": "security-alert",
      "name": "Security Alert",
      "description": "Critical/High vulnerability detected",
      "enabled": true,
      "triggers": [],
      "bellEnabled": true,
      "bellThreshold": "all",
      "templates": {}
    },
    {
      "id": "agent-disconnect",
      "name": "Agent Disconnected",
      "description": "When a remote agent loses connection",
      "enabled": false,
      "triggers": [],
      "bellEnabled": true,
      "bellThreshold": "all",
      "templates": {}
    },
    {
      "id": "agent-reconnect",
      "name": "Agent Reconnected",
      "description": "When a remote agent reconnects after losing connection",
      "enabled": false,
      "triggers": [],
      "bellEnabled": false,
      "bellThreshold": "all",
      "templates": {}
    },
    {
      "id": "container-unhealthy",
      "name": "Container Unhealthy",
      "description": "When a container's Docker health check enters the unhealthy state",
      "enabled": false,
      "triggers": [],
      "bellEnabled": false,
      "bellThreshold": "all",
      "templates": {}
    }
  ],
  "total": 7
}

Response fields

Update a notification rule

Update delivery routing, bell preferences, and/or template overrides for a rule. Only the fields you include are changed. Template keys must resolve to configured notification triggers; action triggers are rejected.

curl -X PATCH http://drydock:3000/api/v1/notifications/update-available \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true,
    "triggers": ["slack.alerts", "ntfy.one"],
    "bellEnabled": true,
    "bellThreshold": "minor",
    "templates": {
      "slack.alerts": {
        "simpleTitle": "${container.name}: ${container.updateKind.remoteValue}",
        "simpleBody": "${container.result.releaseNotes.body}"
      }
    }
  }'

Returns 200 with the updated rule, 400 if the body is invalid or a trigger ID is not recognized, or 404 if the rule ID does not exist.

Preview notification templates

Render draft overrides against representative data without saving them:

curl -X POST http://drydock:3000/api/v1/notifications/update-available/preview \
  -H 'Content-Type: application/json' \
  -d '{
    "triggerId": "slack.alerts",
    "templates": {
      "simpleTitle": "${container.name}: ${container.updateKind.remoteValue}",
      "simpleBody": "${container.result.releaseNotes.body}",
      "batchTitle": "${containers.length} updates available"
    }
  }'

The response contains rendered simpleTitle, simpleBody, and batchTitle strings. Omitted draft fields fall back to the saved rule override, then to the trigger's configured/default template. The endpoint returns 404 for an unknown rule and 400 for an unknown trigger or one that cannot render previews.

Notification outbox

The notification outbox stores failed notification delivery attempts so admins can inspect, retry, or discard them. The outbox API and UI are session-authenticated admin surfaces.

Error body retention

lastError is diagnostic text from the latest failed delivery attempt. It may include downstream notification provider or webhook response bodies when those providers return useful failure text, with Authorization header values redacted before storage. Treat it as admin-visible troubleshooting data, not as sanitized end-user copy.

Outbox API responses expose only a safe payload projection. Full persisted delivery payloads, including full container objects, are not returned by GET /api/v1/notifications/outbox.

List notification outbox entries

curl "http://drydock:3000/api/v1/notifications/outbox?status=dead-letter"

Returns 200 with outbox entries, 400 if status is invalid, or 401 if authentication is required.

Retry a notification outbox entry

curl -X POST http://drydock:3000/api/v1/notifications/outbox/outbox-entry-id/retry

Returns 200 with the requeued entry, 404 if the entry does not exist or is not in dead-letter status, or 500 on an internal error.

Delete a notification outbox entry

curl -X DELETE http://drydock:3000/api/v1/notifications/outbox/outbox-entry-id

Returns 204 on success, 404 if the entry does not exist, or 500 on an internal error.

Audit trail

Returns paginated audit log entries for container lifecycle events, updates, rollbacks, webhooks, and more.

Get audit entries

curl "http://drydock:3000/api/v1/audit?offset=0&limit=25&action=update-applied&container=homeassistant"

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "timestamp": "2024-12-01T10:01:30.000Z",
      "action": "update-applied",
      "containerName": "homeassistant",
      "containerImage": "homeassistant/home-assistant",
      "fromVersion": "2024.11.3",
      "toVersion": "2024.12.0",
      "triggerName": "docker.local",
      "status": "success",
      "details": ""
    }
  ],
  "total": 42,
  "limit": 25,
  "offset": 0,
  "hasMore": true
}

Query parameters

Action types

update-available, update-applied, update-failed, container-update, security-alert, agent-disconnect, container-added, container-removed, rollback, preview, container-start, container-stop, container-restart, webhook-watch, webhook-watch-container, webhook-update, hook-configured, hook-pre-success, hook-pre-failed, hook-post-success, hook-post-failed, auto-rollback, auth-login

Server-Sent Events (SSE)

The /api/v1/events/ui endpoint provides real-time push notifications to the UI via Server-Sent Events.

Connect

curl -N -H "Accept: text/event-stream" http://drydock:3000/api/v1/events/ui

Connection limits: max 10 per IP, max 10 per session. Returns 429 when exceeded.

Reconnection and event replay

Each SSE event carries an id: field (<bootId>:<counter>). On reconnect, browsers automatically send a Last-Event-ID header and the server replays any buffered events since that ID. For clients that cannot set custom headers (for example EventSource in some environments), pass the same value via the ?last-event-id= query parameter instead — the server checks both and the header takes precedence.

The replay buffer is an in-memory 5-minute ring buffer. If the requested event is older than the buffer, the server sends dd:resync-required so the client can refresh full state. If the boot ID does not match the server's current boot (server restarted since the last connection), the server cannot replay events from before the restart; the client should treat that reconnect as a full re-sync.

Event types

Self-update acknowledgment

When a dd:self-update event has requiresAck: true, the UI must POST an acknowledgment before the timeout expires. The clientId and clientToken are provided in the initial dd:connected event.

curl -X POST http://drydock:3000/api/v1/events/ui/self-update/op-abc123/ack \
  -H 'Content-Type: application/json' \
  -d '{"clientId": "client-1", "clientToken": "tok-xyz"}'

SSE message format

event: dd:container-updated
data: { "id": "31a61a...", "name": "homeassistant", ... }

Settings

Persistent server-wide application settings stored in the Drydock database. Unlike Preferences, these values apply to every user and browser.

Get settings

curl http://drydock:3000/api/v1/settings

{
  "internetlessMode": false,
  "updateMode": "manual"
}

Update settings

curl -X PATCH http://drydock:3000/api/v1/settings \
  -H 'Content-Type: application/json' \
  -d '{"updateMode": "notify"}'

{
  "internetlessMode": false,
  "updateMode": "notify"
}

Returns 200 with the updated settings, or 400 if the body is invalid. PUT /api/v1/settings remains a deprecated compatibility alias; because /api/v1 is frozen, removal is deferred to API v2. New integrations should use PATCH.

Preferences

Cross-device sync of UI preferences (theme, layout, dashboard, language, and more) for signed-in users. Opt-in via the Sync across devices toggle in Config > Appearance — see UI Customization for the feature overview. Requires a real, non-anonymous user identity; there is no PUT alias for this endpoint. The examples below assume an authenticated, non-anonymous session (see Authentication); anonymous sessions receive 403.

Get preferences

curl http://drydock:3000/api/v1/preferences

{
  "apiVersion": 1,
  "username": "alice",
  "schemaVersion": null,
  "preferences": null,
  "updatedAt": null
}

schemaVersion, preferences, and updatedAt are null until the user has synced at least once.

Update preferences

Replaces the full stored preferences blob — this is a full replace, not a partial merge.

curl -X PATCH http://drydock:3000/api/v1/preferences \
  -H 'Content-Type: application/json' \
  -d '{"apiVersion": 1, "schemaVersion": 11, "preferences": {"theme": {"family": "dracula"}, "appearance": {"fontSize": 1.1}}}'

{
  "apiVersion": 1,
  "username": "alice",
  "schemaVersion": 11,
  "preferences": {"theme": {"family": "dracula"}, "appearance": {"fontSize": 1.1}},
  "updatedAt": "2026-07-11T12:00:00.000Z"
}

Returns 200 with the preferences envelope, 400 if the body is malformed, 401 if there is no session, 403 if the session is anonymous (sync requires a real user identity), 409 if apiVersion does not match the server's supported version, or 413 if the request body exceeds the global 256 kb JSON body limit.

Container groups

Returns containers grouped by stack or group label. Group priority: dd.group > com.docker.compose.project > com.docker.stack.namespace > ungrouped.

curl http://drydock:3000/api/v1/containers/groups

{
  "data": [
    {
      "name": "monitoring",
      "containers": [
        {
          "id": "31a61a...",
          "name": "prometheus",
          "displayName": "Prometheus",
          "updateAvailable": false
        },
        {
          "id": "e5f6a7...",
          "name": "grafana",
          "displayName": "Grafana",
          "updateAvailable": true
        }
      ],
      "containerCount": 2,
      "updatesAvailable": 1
    },
    {
      "name": null,
      "containers": [
        {
          "id": "abc123...",
          "name": "standalone-app",
          "displayName": "standalone-app",
          "updateAvailable": false
        }
      ],
      "containerCount": 1,
      "updatesAvailable": 0
    }
  ],
  "total": 2
}

Response fields

Authentication routes

When authentication is enabled, these endpoints manage the login flow. Auth routes are mounted at /auth (not /api/auth).

Get authentication status

Returns registered authentication providers and startup registration errors. This endpoint is unauthenticated so the login screen can check auth readiness.

curl http://drydock:3000/api/v1/auth/status

The same status payload is also available at GET /auth/status; GET /api/auth/status remains as the unversioned compatibility alias.

Get available strategies

Returns the list of configured authentication strategies. This endpoint is unauthenticated so the login screen can render.

curl http://drydock:3000/auth/strategies

The { strategies, warnings } response shape from GET /auth/strategies is deprecated and scheduled for removal in v1.8.0. Migrate to GET /api/v1/auth/status; see Deprecations.

A legacy alias is available at GET /api/auth/methods (rate-limited), deprecated and scheduled for removal in v1.7.0 — see Deprecations.

Login

Authenticate with credentials. The response sets a session cookie.

curl -X POST http://drydock:3000/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "..."}'

Get current user

Returns the currently authenticated user. Requires a valid session.

curl http://drydock:3000/auth/user

Logout

End the current session.

curl -X POST http://drydock:3000/auth/logout

When the active auth strategy exposes an OIDC end-session URL, the response includes logoutUrl so the UI can complete IdP logout. If logoutUrl is missing, logout is local-session-only.

Remember me

Store a remember-me preference for the current authenticated session.

curl -X POST http://drydock:3000/auth/remember \
  -H 'Content-Type: application/json' \
  -d '{"remember": true}'

OpenAPI

Machine-readable API documentation is available as an OpenAPI 3.1.0 specification.

curl http://drydock:3000/api/v1/openapi.json

The spec covers HTTP API endpoints with request/response schemas. You can import the URL into tools like Swagger UI, Redoc, or Postman for interactive exploration.