Container API

This API allows to query the state of the watched containers.

Get all containers

This operation lets you get all the watched containers.

curl "http://drydock:3000/api/containers?limit=25&offset=0"

{
  "data": [
    {
      "id": "31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816",
      "name": "homeassistant",
      "watcher": "local",
      "status": "running"
    }
  ],
  "total": 42,
  "limit": 25,
  "offset": 0,
  "hasMore": true
}

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`0`	Maximum number of containers to return (`0` means unbounded; max `200`)
`offset`	integer	`0`	Number of matching containers to skip
`includeVulnerabilities`	boolean	`false`	Include full vulnerability arrays in `data`

Get container summary

Returns a lightweight summary of container and security counts, used by the dashboard sidebar.

curl http://drydock:3000/api/containers/summary

{
  "containers": {
    "total": 12,
    "running": 10,
    "stopped": 2
  },
  "security": {
    "issues": 3
  }
}

Response fields

Field	Type	Description
`containers.total`	integer	Total number of watched containers
`containers.running`	integer	Number of running containers
`containers.stopped`	integer	Number of stopped containers
`security.issues`	integer	Number of containers with critical or high vulnerabilities

Get recent container status

Returns a map of container names to their most recent update status, derived from the last 100 audit log entries. Used by the dashboard to show status badges on containers.

curl http://drydock:3000/api/containers/recent-status

{
  "statuses": {
    "homeassistant": "updated",
    "nginx": "pending",
    "postgres": "failed"
  }
}

Response fields

Field	Type	Description
`statuses`	object	Map of container name to status
`statuses[name]`	string	`updated` (update applied), `pending` (update available), or `failed` (update failed)

Watch all Containers

This operation triggers a manual watch on all containers.

curl -X POST http://drydock:3000/api/containers/watch

{
  "data": [{
  "id":"31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816",
  "name":"homeassistant",
  "watcher":"local",
  "includeTags":"^\\d+\\.\\d+.\\d+$",
  "image":{
    "id":"sha256:d4a6fafb7d4da37495e5c9be3242590be24a87d7edcc4f79761098889c54fca6",
    "registry":{
      "url":"123456789.dkr.ecr.eu-west-1.amazonaws.com"
    },
    "name":"test",
    "tag":{
      "value":"2021.6.4",
      "semver":true
    },
    "digest":{
      "watch":false,
      "repo":"sha256:ca0edc3fb0b4647963629bdfccbb3ccfa352184b45a9b4145832000c2878dd72"
    },
    "architecture":"amd64",
    "os":"linux",
    "created":"2021-06-12T05:33:38.440Z"
  },
  "result":{
    "tag":"2021.6.5"
  },
  "updateAvailable": true
  }],
  "total": 42,
  "limit": 0,
  "offset": 0,
  "hasMore": false
}

Get a Container by id

This operation lets you get a container by id.

curl http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816

{
  "id":"31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816",
  "name":"homeassistant",
  "watcher":"local",
  "includeTags":"^\\d+\\.\\d+.\\d+$",
  "image":{
    "id":"sha256:d4a6fafb7d4da37495e5c9be3242590be24a87d7edcc4f79761098889c54fca6",
    "registry":{
      "url":"123456789.dkr.ecr.eu-west-1.amazonaws.com"
    },
    "name":"test",
    "tag":{
      "value":"2021.6.4",
      "semver":true
    },
    "digest":{
      "watch":false,
      "repo":"sha256:ca0edc3fb0b4647963629bdfccbb3ccfa352184b45a9b4145832000c2878dd72"
    },
    "architecture":"amd64",
    "os":"linux",
    "created":"2021-06-12T05:33:38.440Z"
  },
  "result":{
    "tag":"2021.6.5"
  },
  "updateAvailable": true
}

Get all triggers associated to the container

This operation lets you get the list of triggers associated to the container.

curl http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/triggers

[
  {
    "id": "ntfy.one",
    "type": "ntfy",
    "name": "one",
    "configuration": {
      "topic": "235ef38e-f1db-414a-964f-ce3f2cc8094d",
      "url": "https://ntfy.sh",
      "threshold": "major",
      "mode": "simple",
      "once": true,
      "simpletitle": "New ${kind} found for container ${name}",
      "simplebody": "Container ${container.name} running with ${container.updateKind.kind} ${container.updateKind.localValue} can be updated to ${container.updateKind.kind} ${container.updateKind.remoteValue}${container.result && container.result.link ? "\\n" + container.result.link : ""}",
      "batchtitle": "${containers.length} updates available",
    }
  }
]

Watch a Container

This operation triggers a manual watch on a container.

curl -X POST http://drydock:3000/api/containers/ca0edc3fb0b4647963629bdfccbb3ccfa352184b45a9b4145832000c2878dd72/watch

{
  "id":"31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816",
  "name":"homeassistant",
  "watcher":"local",
  "includeTags":"^\\d+\\.\\d+.\\d+$",
  "image":{
    "id":"sha256:d4a6fafb7d4da37495e5c9be3242590be24a87d7edcc4f79761098889c54fca6",
    "registry":{
      "url":"123456789.dkr.ecr.eu-west-1.amazonaws.com"
    },
    "name":"test",
    "tag":{
      "value":"2021.6.4",
      "semver":true
    },
    "digest":{
      "watch":false,
      "repo":"sha256:ca0edc3fb0b4647963629bdfccbb3ccfa352184b45a9b4145832000c2878dd72"
    },
    "architecture":"amd64",
    "os":"linux",
    "created":"2021-06-12T05:33:38.440Z"
  },
  "result":{
    "tag":"2021.6.5"
  },
  "updateAvailable": true
}

Run a trigger on the container

This operation lets you manually run a trigger on the container.

curl -X POST http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/triggers/ntfy/one

For containers managed by a remote agent, use the 4-segment variant to route the trigger through the agent:

curl -X POST http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/triggers/ntfy/one/agent1

This operation triggers a direct container update — pulling the new image, stopping the old container, and recreating it with the updated image. This is equivalent to clicking "Update now" in the UI. Requires the Docker trigger to be configured for the container's watcher and DD_SERVER_FEATURE_CONTAINERACTIONS to be enabled.

Returns 200 with the updated container on success, 400 if no update is available, 403 if container actions are disabled, 404 if the container or Docker trigger is not found, or 500 on update failure.

curl -X POST http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/update

Update container update policy (skip/snooze)

This operation lets you control per-container update suppression policy (stored in drydock DB):

skip-current: skip the currently detected remote tag or digest
remove-skip: remove a single previously skipped tag or digest (requires kind and value)
clear-skips: remove skipTags and skipDigests
snooze: suppress update notifications until a date (supports days or explicit snoozeUntil)
unsnooze: remove snoozeUntil
clear: remove all update policy

curl -X PATCH http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/update-policy \
  -H 'Content-Type: application/json' \
  -d '{"action":"skip-current"}'

# Remove a single skipped tag
curl -X PATCH http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/update-policy \
  -H 'Content-Type: application/json' \
  -d '{"action":"remove-skip","kind":"tag","value":"1.2.3"}'

# Remove a single skipped digest
curl -X PATCH http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/update-policy \
  -H 'Content-Type: application/json' \
  -d '{"action":"remove-skip","kind":"digest","value":"sha256:abc123..."}'

curl -X PATCH http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/update-policy \
  -H 'Content-Type: application/json' \
  -d '{"action":"snooze","days":7}'

Get security vulnerability overview

This operation returns pre-aggregated vulnerability data grouped by image across all scanned containers. Used by the Security view to display vulnerability summaries without loading every container individually.

curl http://drydock:3000/api/containers/security/vulnerabilities

The response includes total and scanned container counts, the latest scan timestamp, and an images array where each entry groups vulnerabilities by image name with container IDs and an optional update severity summary.

Get latest vulnerability scan result

This operation returns the latest persisted vulnerability scan (safe-pull gate result) for a container. When no scan was run yet, it returns status: "not-scanned" with an empty result set.

curl http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/vulnerabilities

Run an on-demand security scan

This operation triggers a vulnerability scan, optional signature verification, and optional SBOM generation for a container. The scan targets the update candidate image when available, falling back to the current image tag. Results are persisted to container.security and the updated container is returned.

Requires DD_SECURITY_SCANNER=trivy to be configured.

curl -X POST http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/scan

Returns 200 with the updated container on success, 400 if security scanner is not configured, 404 if the container is not found, or 500 on scan failure.

Get SBOM for a container

This operation returns the latest SBOM document for a container in the requested format.

curl http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/sbom?format=spdx-json

Get container logs

Returns stdout/stderr output from a container. For agent-managed containers, the request is proxied through the agent connection.

curl "http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/logs?tail=100"

Query parameters

Parameter	Type	Default	Description
`tail`	integer	100	Number of lines to return from the end of the log
`since`	integer	0	Unix timestamp (seconds) — only return logs after this time
`timestamps`	boolean	true	Include timestamps in output

Returns 200 with { "logs": "..." } on success, 404 if the container is not found, or 500 on failure.

Reveal container environment variables

Returns the full (unredacted) runtime environment variables for a container. Environment values in the standard container response are redacted to *** for sensitive keys. This endpoint reveals the actual values and creates an audit trail entry.

Rate-limited to 10 requests per minute.

curl -X POST http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/env/reveal

{
  "env": [
    { "key": "TZ", "value": "America/New_York", "sensitive": false },
    { "key": "DATABASE_PASSWORD", "value": "s3cret", "sensitive": true }
  ]
}

Response fields

Field	Type	Description
`env[].key`	string	Environment variable name
`env[].value`	string	Unredacted value
`env[].sensitive`	boolean	Whether the key matches known sensitive patterns (passwords, tokens, secrets)

Returns 200 with the env array on success, 404 if the container is not found, or 429 if rate-limited.

Container action auth model: /start, /stop, /restart, and /update are authentication-gated only. In current single-operator deployments, any authenticated user can execute these actions for any container.

Start a container

This operation starts a stopped container. Requires DD_SERVER_FEATURE_CONTAINERACTIONS to be enabled.

curl -X POST http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/start

Stop a container

This operation stops a running container. Requires DD_SERVER_FEATURE_CONTAINERACTIONS to be enabled.

curl -X POST http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/stop

Restart a container

This operation restarts a container. Requires DD_SERVER_FEATURE_CONTAINERACTIONS to be enabled.

curl -X POST http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/restart

Preview an update

This operation returns a dry-run preview of what an update would change, without executing it.

curl -X POST http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/preview

Get container backups

This operation returns all image backups for a container, sorted by most recent first.

curl http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/backups

[
  {
    "id": "abc123",
    "containerId": "31a61a8305ef...",
    "containerName": "homeassistant",
    "imageName": "homeassistant/home-assistant",
    "imageTag": "2021.6.4",
    "imageDigest": "sha256:...",
    "timestamp": "2021-06-15T10:30:00.000Z",
    "triggerName": "docker.local"
  }
]

Rollback a container

This operation rolls back a container to a previously backed-up image. If no backupId is provided, the most recent backup is used. Rollback is destructive and requires explicit confirmation via X-DD-Confirm-Action: container-rollback.

curl -X POST http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/rollback \
  -H 'X-DD-Confirm-Action: container-rollback' \
  -H 'Content-Type: application/json' \
  -d '{"backupId": "abc123"}'

Returns 200 on success, 404 if the container/backup/trigger is not found, or 428 if confirmation is missing.

Get update/rollback history

Returns the persisted update and rollback operation history for a container, sorted by most recent first. Each entry tracks the full lifecycle of an update (phases, status, versions, rollback reason if applicable).

curl http://drydock:3000/api/containers/31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816/update-operations

[
  {
    "id": "a1b2c3d4-...",
    "containerName": "homeassistant",
    "status": "succeeded",
    "phase": "succeeded",
    "createdAt": "2024-12-01T10:00:00.000Z",
    "updatedAt": "2024-12-01T10:01:30.000Z",
    "containerId": "31a61a8305ef...",
    "triggerName": "docker.local",
    "fromVersion": "2024.11.3",
    "toVersion": "2024.12.0",
    "targetImage": "homeassistant/home-assistant:2024.12.0"
  },
  {
    "id": "e5f6a7b8-...",
    "containerName": "homeassistant",
    "status": "rolled-back",
    "phase": "rolled-back",
    "createdAt": "2024-11-20T08:00:00.000Z",
    "updatedAt": "2024-11-20T08:02:00.000Z",
    "containerId": "31a61a8305ef...",
    "fromVersion": "2024.11.2",
    "toVersion": "2024.11.3",
    "rollbackReason": "Health check failed"
  }
]

Response fields

Field	Type	Description
`id`	string	Unique operation ID
`containerName`	string	Container name
`status`	string	`in-progress`, `succeeded`, `rolled-back`, or `failed`
`phase`	string	Current phase: `prepare`, `renamed`, `new-created`, `old-stopped`, `new-started`, `health-gate`, `health-gate-passed`, `succeeded`, `rollback-started`, `rolled-back`, `rollback-failed`
`createdAt`	string	ISO 8601 timestamp when the operation started
`updatedAt`	string	ISO 8601 timestamp of the last phase transition
`containerId`	string	Container ID
`triggerName`	string	Trigger that initiated the update
`fromVersion`	string	Previous image tag or digest
`toVersion`	string	Target image tag or digest
`targetImage`	string	Full target image reference
`rollbackReason`	string	Reason for rollback (only present on rolled-back operations)
`lastError`	string	Error message (only present on failed operations)

Returns 200 with the operations array on success, or 404 if the container is not found.

Delete a Container

This operation lets you delete a container by id. Requires DD_SERVER_FEATURE_DELETE to be enabled. Delete is destructive and requires explicit confirmation via X-DD-Confirm-Action: container-delete.

curl -X DELETE http://drydock:3000/api/containers/ca0edc3fb0b4647963629bdfccbb3ccfa352184b45a9b4145832000c2878dd72 \
  -H 'X-DD-Confirm-Action: container-delete'

Returns 204 on success, 403 if delete is disabled, 404 if the container does not exist, or 428 if confirmation is missing.

Container API

Get all containers

Query parameters

Get container summary

Response fields

Get recent container status

Response fields

Watch all Containers

Get a Container by id

Get all triggers associated to the container

Watch a Container

Run a trigger on the container

Update a container

Update container update policy (skip/snooze)

Get security vulnerability overview

Get latest vulnerability scan result

Run an on-demand security scan

Get SBOM for a container

Get container logs

Query parameters

Reveal container environment variables

Response fields

Start a container

Stop a container

Restart a container

Preview an update

Get container backups

Rollback a container

Get update/rollback history

Response fields

Delete a Container

On this page