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

Container Logs

Returns stdout/stderr output from a container running on the Agent.

curl -H "X-Dd-Agent-Secret: <SECRET>" \
  "http://agent:3000/api/containers/:id/logs?tail=100"

Query parameters are the same as the controller container logs endpoint.

Application Log Entries

Returns application log entries from the Agent's in-memory ring buffer.

curl -H "X-Dd-Agent-Secret: <SECRET>" \
  "http://agent:3000/api/log/entries?level=warn&tail=50"

Query parameters

Parameter	Type	Description
`level`	string	Filter by minimum log level
`component`	string	Filter by component name
`tail`	integer	Number of entries to return from the end
`since`	integer	Unix timestamp (seconds) -- only entries after this time

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

Batch execution

Execute a trigger for multiple containers in a single request.

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

Health Check

Returns the Agent's uptime. This endpoint is unauthenticated and intended for Docker HEALTHCHECK directives.

curl http://agent:3000/health

{
  "uptime": 3600.123
}

Agent API

On this page