Agent API

The Agent exposes specific endpoints for the Controller to synchronize state and receive events.

The Agent exposes specific endpoints for the Controller to synchronize state and receive events. These are generally internal APIs used by the Controller but are documented here for reference or advanced debugging.

Authentication is required for all endpoints via the X-Dd-Agent-Secret header.

Get State

Returns a snapshot of the Agent's current state (containers, watchers, triggers).

# Get Containers
curl -H "X-Dd-Agent-Secret: <SECRET>" http://agent:3000/api/containers

# Get Watchers
curl -H "X-Dd-Agent-Secret: <SECRET>" http://agent:3000/api/watchers

# Get Triggers
curl -H "X-Dd-Agent-Secret: <SECRET>" http://agent:3000/api/triggers

Watch Resources

Trigger a manual watch on a specific watcher or container hosted by the Agent.

# Watch a specific watcher (discovery)
curl -X POST \
  -H "X-Dd-Agent-Secret: <SECRET>" \
  http://agent:3000/api/watchers/:type/:name

# Watch a specific container (discovery)
curl -X POST \
  -H "X-Dd-Agent-Secret: <SECRET>" \
  http://agent:3000/api/watchers/:type/:name/container/:id

Delete a Container

Delete a container from the Agent's state.

Note: This operation requires DD_SERVER_FEATURE_DELETE to be enabled on the Agent.

curl -X DELETE \
  -H "X-Dd-Agent-Secret: <SECRET>" \
  http://agent:3000/api/containers/:id

Real-time Events (SSE)

Subscribes to real-time updates from the Agent using Server-Sent Events (SSE).

The Agent pushes events when containers are added, updated, or removed.

Endpoint

curl -N -H "X-Dd-Agent-Secret: <SECRET>" -H "Accept: text/event-stream" http://agent:3000/api/events

Protocol

Events are sent as JSON objects with the following structure:

data: {
  "type": "event_type",
  "data": { ...payload... }
}

Supported Events

`dd:ack`

Sent immediately upon connection to confirm the handshake.

{
  "type": "dd:ack",
  "data": {
    "version": "1.0.0"
  }
}

`dd:container-added`

Sent when a new container is discovered.

{
  "type": "dd:container-added",
  "data": { ...container_object... }
}

`dd:container-updated`

Sent when an existing container is updated (e.g. status change, new image tag).

{
  "type": "dd:container-updated",
  "data": { ...container_object... }
}

`dd:container-removed`

Sent when a container is removed (e.g. stopped and pruned).

{
  "type": "dd:container-removed",
  "data": {
    "id": "container_id"
  }
}

Execute Remote Trigger

Executes a specific trigger on the Agent (e.g., to update a container).

curl -X POST \
  -H "X-Dd-Agent-Secret: <SECRET>" \
  -H "Content-Type: application/json" \
  -d '{ ...container_json... }' \
  http://agent:3000/api/triggers/:type/:name

Agent API

On this page