When working with a private Docker registry (using Registry HTTP API v2), it’s often useful to programmatically list available repositories and images. Whether you’re managing your own registry or building automation tools, understanding how to query the Docker Registry API helps streamline your workflow.
In this post, you’ll learn:
- ✅ How to query a Docker Registry v2 API
- 📦 How to list all image repositories
- 🏷️ How to fetch all tags for a specific image
- 🔐 How to handle basic authentication (if required)
🧠 Prerequisite: What Is Docker Registry v2?
Docker Registry v2 is the API used by Docker to store and retrieve container images. If you’re running a private registry (e.g., with docker run -d registry:2), it supports endpoints for:
- Listing repositories
- Listing image tags
- Deleting layers (with certain setups)
✅ 1. List All Repositories (Images)
To list all repositories (top-level image names):
📦 API Endpoint:
GET /v2/_catalog
✅ Example with curl:
curl http://your-registry-domain:5000/v2/_catalog
🧪 Sample Response:
{
"repositories": [
"myapp",
"nginx-custom",
"backend-service"
]
}
📌 This returns an array of repository names stored in the registry.
✅ 2. List All Tags for a Repository
To list all tags for a specific image/repository:
🏷️ API Endpoint:
GET /v2/<repository-name>/tags/list
✅ Example:
curl http://your-registry-domain:5000/v2/myapp/tags/list
🧪 Sample Response:
{
"name": "myapp",
"tags": [
"latest",
"v1.0",
"v2.1"
]
}
🔐 3. Accessing a Secured Registry (with Authentication)
If your registry is protected (e.g., with a reverse proxy and basic auth), use:
curl -u username:password https://your-registry.com/v2/_catalog
Or store credentials in a .netrc file, or configure Docker login:
docker login your-registry.com
Then use the Authorization token returned to query the API with curl or httpie.
🧪 Full Script Example
Here’s a quick bash script to list all images and their tags:
#!/bin/bash
REGISTRY_URL="http://localhost:5000"
# Get all repositories
repos=$(curl -s "$REGISTRY_URL/v2/_catalog" | jq -r '.repositories[]')
for repo in $repos; do
echo "Repository: $repo"
curl -s "$REGISTRY_URL/v2/$repo/tags/list" | jq
echo ""
done
✅ Requires jq to parse JSON.
🧠 Common Gotchas
| Problem | Solution |
|---|---|
| API not responding | Make sure Docker registry is running on port 5000 |
| Empty catalog | You may not have pushed any images yet |
| Auth errors | Add -u for username/password or configure your login properly |
🏁 Final Thoughts
The Docker Registry v2 API makes it easy to programmatically inspect your private registry. Whether you’re listing images or tags for automation, backups, or dashboards, these simple API calls can be integrated into CI/CD workflows or admin tools.
