Getting Started with the Docker Hub API — Docker Hub API

When to use this API

When you need Docker Hub catalog metadata programmatically — pull counts, tag listings, available architectures, repository maintenance status, or namespace browsing. This is Hub metadata, not image content; if you need to pull actual image layers or verify manifests at the registry level, reach for the Docker Registry API (OCI Distribution Spec) instead. The Docker Hub API is surprisingly useful for answering questions that are awkward to surface any other way: "Is this image still actively maintained?", "Which tags does nginx publish for ARM?", "Is the official CentOS image deprecated?" No auth required for public repositories.

Checking a repository's status and pull count

"Is the nginx image actively maintained? How popular is it?" The /repositories/{namespace}/{repository}/ endpoint returns the full Hub metadata for a single image, including pull count, last push date, and the full README as a markdown string. For official Docker images, the namespace is always library.

curl "https://hub.docker.com/v2/repositories/library/nginx/" | head -c 10000

{
  "user": "library",
  "name": "nginx",
  "namespace": "library",
  "repository_type": "image",
  "status_description": "active",
  "description": "Official build of Nginx.",
  "is_private": false,
  "is_automated": false,
  "star_count": 21244,
  "pull_count": 12916987208,
  "last_updated": "2026-04-08T04:52:59.85304Z",
  "last_modified": "2026-04-07T18:13:33.599972Z",
  "hub_user": "stackbrew"
}

hub_user is "stackbrew" — the original Docker Hub bot account that seeded the official library images, not the nginx project itself. That's the fingerprint of every Docker-curated official image: Docker owns the namespace, upstream provides the source. last_updated is when the image was last pushed to the registry; last_modified is when Hub's own catalog metadata changed. For liveness checks, last_updated is the one to watch. pull_count at nearly 13 billion means this image is pulled thousands of times per second globally, making it the most-pulled image on Hub by a wide margin.

The nginx image on Docker Hub is actively maintained — last pushed on April 8, 2026 — with nearly 13 billion total pulls. It's an official Docker library image curated by Docker using source from the nginx project.

Listing available tags and supported architectures

"What tags exist for nginx, and does it support ARM?" The /repositories/{namespace}/{repository}/tags/ endpoint returns tags with per-architecture image manifests nested inside each result. Each tag entry contains an images array — one entry per supported architecture — with its own digest, size, and push/pull timestamps.

curl "https://hub.docker.com/v2/repositories/library/nginx/tags/?page_size=3" | head -c 10000

{
  "count": 1105,
  "next": "https://hub.docker.com/v2/repositories/library/nginx/tags/?page=2&page_size=3",
  "results": [
    {
      "name": "latest",
      "images": [
        {
          "architecture": "amd64",
          "os": "linux",
          "size": 62938395,
          "digest": "sha256:f1e4ce3095f46ab65fd053991508a2433e2d7b45f6d8260c93d69c37d4307350",
          "last_pulled": "2026-04-09T00:21:37.390275389Z",
          "last_pushed": "2026-04-07T19:50:23.21221856Z"
        },
        {
          "architecture": "arm",
          "variant": "v5",
          "os": "linux",
          "size": 54147985,
          "digest": "sha256:fd8625f6a0eda521a08b828127c944d711092653db247f2b1f45e5ff3f667a46",
          "last_pulled": "2026-04-09T00:21:54.573279322Z",
          "last_pushed": "2026-04-07T19:50:24.291199933Z"
        }
      ]
    }
  ]
}

nginx has 1,105 tags — not 1,105 distinct image versions. That number includes semantic versions (1.29.8), rolling aliases (latest, mainline, stable), OS variant tags (alpine, bookworm, trixie), and digest-pinned tags, many of which point to the same underlying layers. The images array inside each tag is the multi-arch manifest list: each architecture gets its own digest and its own 60 MB binary, independently pushed and cached. variant appears on ARM entries (v5, v7) but is null on amd64 — ARM's sub-architecture variants are a real dimension of the image matrix that this API exposes clearly.

Yes, nginx supports ARM. The latest tag includes builds for amd64, arm/v5, arm/v7, arm64, and several others. There are 1,105 total tags — including 1.29.8, Debian and Alpine variants, and rolling aliases like mainline. ARM images are available as both arm/v5 and arm/v7 variants.

Spotting deprecated or unmaintained official images

"Is CentOS safe to use as a base image?" The namespace listing at /repositories/library/ returns all official images with their descriptions and last-push timestamps. The description field is where maintainers embed deprecation notices, and last_updated surfaces when the image was last pushed.

curl "https://hub.docker.com/v2/repositories/library/?page_size=5" | head -c 10000

{
  "count": 179,
  "results": [
    {
      "name": "centos",
      "description": "DEPRECATED; The official build of CentOS.",
      "star_count": 7782,
      "pull_count": 1181568424,
      "last_updated": "2022-12-09T19:13:54.287062Z",
      "status_description": "active"
    },
    {
      "name": "busybox",
      "description": "Busybox base image.",
      "star_count": 3493,
      "pull_count": 12473492261,
      "last_updated": "2026-03-24T19:59:26.535531Z",
      "status_description": "active"
    },
    {
      "name": "scratch",
      "description": "an explicitly empty image, especially for building images \"FROM scratch\"",
      "repository_type": null,
      "pull_count": 268577,
      "last_updated": "2013-06-25T00:07:08Z",
      "storage_size": null,
      "status_description": "active"
    }
  ]
}

status_description is "active" for centos even though it's deprecated — Docker has not archived the catalog record, just stopped pushing new images. The real signals are last_updated: "2022-12-09" combined with the DEPRECATED prefix in description. scratch is the edge case the API models cleanly rather than papering over: repository_type is null, storage_size is null, and the pull count is a modest 268,577 despite being the implicit foundation of every FROM scratch Dockerfile — because no one actually pulls scratch directly.

The CentOS image is deprecated and no longer maintained — last pushed December 2022, and the description explicitly says so. For a minimal base, busybox is still actively updated (last pushed March 2026) or use debian for a fuller environment.

Pitfalls

status_description: "active" does not mean maintained. CentOS shows "active" three years after its last push. Check last_updated and scan the description field for a DEPRECATED prefix — that's the actual signal.
The /search/repositories/ endpoint returned empty results in all tested probes, even for common terms. Rely on namespace listings (/repositories/{namespace}/) or direct repository lookups instead of search if you need reliable results.
The library namespace is for official Docker images only. Third-party images live under their own namespaces — bitnami/nginx is at /repositories/bitnami/nginx/, not /repositories/library/nginx/. Official images have no username prefix on the Hub UI, which creates an asymmetry: nginx in a Dockerfile maps to library/nginx in this API.
Tag listings paginate at 10 by default and can have thousands of entries. nginx has 1,105 tags. Use page_size to control response size and next to paginate. Fetching all tags for a busy image without a page limit will burn time and tokens for little benefit.

One-line summary for the user

I can look up Docker Hub catalog metadata — pull counts, available tags with per-architecture digests, maintenance status, and official image namespaces — without authentication, but I can't pull actual image layers or verify image content through this API.