Watcher API

Get all Watchers

This operation lets you get all the configured watchers.

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

{
   "data": [
      {
      "id":"docker.local",
      "type":"docker",
      "name":"local",
      "configuration":{
         "socket":"/var/run/docker.sock",
         "port":2375,
         "cron":"0 */6 * * *",
         "watchbydefault":true
      },
      "metadata": {
         "lastRunAt": "2026-03-20T21:44:11.782Z",
         "nextRunAt": "2026-03-20T22:00:00.000Z"
      }
      }
   ],
   "total": 1,
   "limit": 0,
   "offset": 0,
   "hasMore": false
}

Response fields

metadata.lastRunAt is populated after at least one watch run has completed. metadata.nextRunAt reflects the next effective update-check time after applying watcher scheduling rules. When jitter is enabled, actual execution may drift within the configured jitter window.

Get a Watcher by id

This operation lets you get a specific Watcher.

curl http://drydock:3000/api/v1/watchers/docker/local

{
   "id":"docker.local",
   "type":"docker",
   "name":"local",
   "configuration":{
      "socket":"/var/run/docker.sock",
      "port":2375,
      "cron":"0 */6 * * *",
      "watchbydefault":true
   },
   "metadata":{
      "lastRunAt":"2026-03-20T21:44:11.782Z",
      "nextRunAt":"2026-03-20T22:00:00.000Z"
   }
}

Agent-scoped lookup

To fetch a watcher registered on a specific agent, append the agent name:

curl http://drydock:3000/api/v1/watchers/docker/local/agent1

Refresh inventory

Send an empty JSON object to POST /api/v1/watchers/{type}/{name}/inventory for a local watcher, or POST /api/v1/watchers/{type}/{name}/{agent}/inventory for an exact agent-scoped watcher. This operation requires the containers:watch API-key scope. It refreshes Docker container inventory without registry checks and never falls back to the full-watch operation.

The response contains context, containers, removedIds, errors, and authoritative. The context identifies the inventory operation with a UUID operationId and its exact source (type, name, and optional agent). Container runtime secrets are redacted in this public response.

containers is the final persisted inventory for that source, not a list or count of changed containers. An empty inventory with authoritative: true is successful. Failed observations retain last-known records and return HTTP 200 with authoritative: false and sanitized errors containing phase, optional container id, and message. Superseded requests also return a stale diagnostic.

Missing watchers return 404, unsupported providers return 501, disconnected agents return 503, and the 30-second request deadline returns 504. An unexpected operation failure returns 500. A timed-out or superseded request cannot later apply inventory writes; independently scheduled registry scans remain unchanged.

Local Docker watchers and connected Portwing controller-Docker delegates support this operation. Native agents must explicitly advertise metadata.inventoryRefreshSupported: true; an older agent with no capability field is unsupported and is never probed with a full-watch request.

The authenticated native-agent route is POST /api/watchers/{type}/{name}/inventory. Its internal body contains only a controller-generated UUIDv4 operationId, shared by its HTTP response and dd:inventory-added, dd:inventory-updated, and dd:inventory-removed SSE envelopes. These additive events leave the existing full-watch wire contract unchanged. Controllers ignore unsolicited inventory events and events from expired operations. Agent-to-controller replication retains raw runtime values; public responses and ordinary UI lifecycle events remain redacted.