Docker Has a Free API: Here's How to Use It for Container Automation

#docker #devops #api #automation

Docker Hub provides a powerful free API that most developers don't know about. You can search images, check tags, get vulnerability scans, and automate your entire container workflow — all without paying a cent.

Why Use the Docker Hub API?

Most teams manually browse Docker Hub to find images. But the API lets you:

Search 100K+ container images programmatically
Check tags and digests before pulling
Monitor vulnerabilities in your base images
Automate image updates in CI/CD pipelines

Getting Started

Docker Hub API is at https://hub.docker.com/v2/. No API key needed for public data:

curl -s "https://hub.docker.com/v2/search/repositories/?query=python&page_size=5" \
  | jq '.results[] | {name: .repo_name, stars: .star_count, pulls: .pull_count}'

Response:

{
  "name": "library/python",
  "stars": 9200,
  "pulls": 1500000000
}

List Tags for an Image

curl -s "https://hub.docker.com/v2/repositories/library/node/tags/?page_size=5" \
  | jq '.results[] | {name: .name, size_mb: (.full_size / 1048576 | floor), last_updated: .last_updated}'

This is incredibly useful for:

Checking if a specific version exists
Comparing image sizes between tags
Finding the latest digest for pinning

Authentication for Private Repos

For private repositories, get a JWT token:

TOKEN=$(curl -s -H "Content-Type: application/json" \
  -X POST https://hub.docker.com/v2/users/login/ \
  -d '{"username": "your-user", "password": "your-pass"}' | jq -r .token)

curl -s -H "Authorization: JWT $TOKEN" \
  "https://hub.docker.com/v2/repositories/your-org/?page_size=100" | jq '.results[] | .name'

Monitor Image Vulnerabilities

Combine with Docker Scout API to check CVEs:

import requests

def check_image_tags(image, max_tags=10):
    url = f"https://hub.docker.com/v2/repositories/library/{image}/tags/"
    resp = requests.get(url, params={"page_size": max_tags})
    tags = resp.json()["results"]

    for tag in tags:
        size_mb = tag["full_size"] / 1048576
        print(f"{tag['name']:20s} {size_mb:8.1f} MB  Updated: {tag['last_updated'][:10]}")

check_image_tags("python")
check_image_tags("node")

Automate Base Image Updates

Here's a script that checks if your base images have newer versions:

import requests
from datetime import datetime, timedelta

def check_stale_images(images, days_threshold=30):
    stale = []
    for image in images:
        url = f"https://hub.docker.com/v2/repositories/library/{image}/tags/"
        resp = requests.get(url, params={"page_size": 1, "name": "latest"})
        if resp.status_code == 200:
            tags = resp.json().get("results", [])
            if tags:
                updated = datetime.fromisoformat(tags[0]["last_updated"].replace("Z", "+00:00"))
                age = (datetime.now(updated.tzinfo) - updated).days
                if age > days_threshold:
                    stale.append({"image": image, "days_old": age})
    return stale

result = check_stale_images(["python", "node", "nginx", "postgres", "redis"])
for img in result:
    print(f"WARNING: {img['image']}:latest is {img['days_old']} days old")

Webhook Automation

Docker Hub supports webhooks for automated builds:

from flask import Flask, request

app = Flask(__name__)

@app.route("/docker-webhook", methods=["POST"])
def handle_webhook():
    data = request.json
    repo = data["repository"]["repo_name"]
    tag = data["push_data"]["tag"]
    print(f"New push: {repo}:{tag}")
    return "OK", 200

Rate Limits

User Type	Pull Limit	API Limit
Anonymous	100/6hr	100/min
Free account	200/6hr	300/min
Pro/Team	Unlimited	1000/min

Real-World Use Case

A DevOps engineer at a fintech startup used the Docker Hub API to build an automated compliance checker. Every morning, it scanned all production images for known CVEs and Slack-notified the team. What used to take 2 hours of manual checking now runs in 30 seconds.