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

[
   {
  "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
}
]

Watch all Containers

This operation triggers a manual watch on all containers.

curl -X POST http://drydock:3000/api/containers/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
}]

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 the containers 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

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
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"}'

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

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.

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.

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

Delete a Container

This operation lets you delete a container by id. Requires DD_SERVER_FEATURE_DELETE to be enabled.

curl -X DELETE http://drydock:3000/api/containers/ca0edc3fb0b4647963629bdfccbb3ccfa352184b45a9b4145832000c2878dd72