API v1

Everything D2HA shows is available as JSON under /api/v1, with a bearer token: the Home Assistant integration uses it, and so can your scripts.

The contract

The complete reference, with every field, is API.md. Within v1 changes only add things: clients must ignore fields they do not know.

Authentication

Create a token in Settings → Home Assistant and send it in the Authorization header:

D2HA_URL=http://localhost:12021
D2HA_TOKEN=paste-the-token-here

curl -s -H "Authorization: Bearer $D2HA_TOKEN" "$D2HA_URL/api/v1/info"

A wrong or revoked token gets 401. Writes (POST, PUT) are limited to 30 per minute per address.

Reading

Endpoint	Returns
`GET /info`	Version, API version, read-only mode, Docker version, the last and next check, and counts
`GET /containers`	Every container with its state, health, update status and versions. `?ha=1`: only those shown in Home Assistant, without D2HA.
`GET /containers/<key>/notes`	The release notes of the new version, as Markdown
`GET /jobs`, `GET /jobs/<id>`	Jobs queued or running, or one job

Containers are identified by their key (stack and name, such as monitoring_grafana): it survives updates, while the Docker id changes.

curl -s -H "Authorization: Bearer $D2HA_TOKEN" "$D2HA_URL/api/v1/containers" \
  | jq -r '.containers[] | select(.update == "available") | "\(.name): \(.installed_version) -> \(.latest_version)"'

Actions

Endpoint	Does
`POST /check`	Starts a check now
`POST /containers/<key>/update`	Updates one container
`POST /update-all`	Updates every container with an update, one at a time
`POST /images/prune`	Deletes the unused images

Updates and cleanup answer 202 with a job that runs in the background, one at a time. Follow it with GET /jobs/<id> every second or two, or with GET /jobs/<id>/events (Server-Sent Events).

curl -s -X POST -H "Authorization: Bearer $D2HA_TOKEN" \
  "$D2HA_URL/api/v1/containers/monitoring_grafana/update"

# {"id": "a1b2c3d4e5f6", "kind": "update", "state": "queued", ...}

curl -s -H "Authorization: Bearer $D2HA_TOKEN" "$D2HA_URL/api/v1/jobs/a1b2c3d4e5f6"

A job goes through queued, running and ends done or failed, with the phase (pull, stop, create, start, cleanup) and a percentage while it downloads.

Errors

Errors are {"error": "<code>"}:

Status	`error`	When
400	`bad_request`	The body is not what the endpoint expects
400	`self_update`, `proxy_update`	The container is D2HA itself, or its socket proxy
401	`unauthorized`	No valid token
403	`read_only`	D2HA runs with `D2HA_READ_ONLY=true`
404	`not_found`, `no_notes`	Unknown container or job, or no release notes
409	`nothing_to_update`	Update all with nothing to update
429	`rate_limited`	Too many writes: try again later

Good to know

Logs are for the web interface only: the token cannot read them.

Something wrong or missing on this page? Open an issue.