docker-facts

Does this image:tag exist, how big is it, and which platforms does it cover? Use this before writing a FROM line or a compose file. On a hit it returns size, platforms, arm64/amd64 support and the digest. On a miss it says whether the IMAGE exists but the tag is wrong, and lists real tags newest first so the caller can correct itself. Defaults to tag "latest" when none is given.

{
  "type": "object",
  "properties": {
    "tag": {
      "type": "string",
      "x-in": "query",
      "default": "latest",
      "description": "Tag to check, e.g. \"20-alpine\". Defaults to \"latest\"."
    },
    "name": {
      "type": "string",
      "x-in": "query",
      "description": "Docker image name as you would write it in a FROM line: \"node\", \"postgres\", \"grafana/grafana\". Official images may omit the \"library/\" prefix."
    }
  },
  "required": [
    "name"
  ]
}

{
  "type": "object",
  "properties": {
    "tag": {
      "type": "string"
    },
    "image": {
      "type": "string"
    },
    "digest": {
      "type": "string",
      "nullable": true,
      "description": "Content digest, for pinning."
    },
    "exists": {
      "type": "boolean",
      "description": "Whether this exact image:tag exists on Docker Hub."
    },
    "status": {
      "type": "string",
      "nullable": true,
      "description": "Docker Hub tag status, e.g. \"active\"."
    },
    "meaning": {
      "type": "string",
      "description": "One sentence, safe to show a user verbatim."
    },
    "size_mb": {
      "type": "number",
      "nullable": true,
      "description": "Compressed size in MB."
    },
    "platforms": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "os/arch strings this tag was built for, e.g. \"linux/arm64\"."
    },
    "reference": {
      "type": "string",
      "description": "The full reference, safe to paste into a FROM line."
    },
    "suggestion": {
      "type": "string",
      "nullable": true,
      "description": "Present only on a miss: the most recently updated real tag."
    },
    "image_exists": {
      "type": "boolean",
      "description": "Present only on a miss. Distinguishes a wrong tag from a wrong image name."
    },
    "last_updated": {
      "type": "string",
      "nullable": true,
      "description": "When the tag was last pushed (ISO 8601). A tag untouched for years is usually the wrong choice."
    },
    "available_tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Present only on a miss: real tags, newest first, so the caller can correct itself."
    },
    "supports_amd64": {
      "type": "boolean"
    },
    "supports_arm64": {
      "type": "boolean",
      "description": "Answers the Apple Silicon and Graviton question directly."
    }
  },
  "required": [
    "image",
    "tag",
    "exists",
    "meaning"
  ]
}

Repository facts: official status, pulls, stars, whether it is archived. Use to judge whether an image is the canonical one and still maintained. Archived images still pull but receive no security patches.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "x-in": "query",
      "description": "Docker image name as you would write it in a FROM line: \"node\", \"postgres\", \"grafana/grafana\". Official images may omit the \"library/\" prefix."
    }
  },
  "required": [
    "name"
  ]
}

{
  "type": "object",
  "properties": {
    "image": {
      "type": "string"
    },
    "pulls": {
      "type": "integer",
      "nullable": true
    },
    "stars": {
      "type": "integer",
      "nullable": true
    },
    "exists": {
      "type": "boolean"
    },
    "hub_url": {
      "type": "string",
      "description": "Page a human can open."
    },
    "official": {
      "type": "boolean",
      "description": "True for Docker Official Images (the \"library\" namespace)."
    },
    "description": {
      "type": "string",
      "nullable": true
    },
    "is_archived": {
      "type": "boolean",
      "description": "Archived images still pull but receive no further updates, including security patches."
    },
    "last_updated": {
      "type": "string",
      "nullable": true
    }
  }
}

Real tags for an image, most recently updated first. Use when choosing a tag rather than verifying one. Each entry carries size and platform list, so a choice can be made without a second call.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "x-in": "query",
      "description": "Docker image name as you would write it in a FROM line: \"node\", \"postgres\", \"grafana/grafana\". Official images may omit the \"library/\" prefix."
    },
    "limit": {
      "type": "integer",
      "x-in": "query",
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "description": "How many tags to return, 1 to 100. Defaults to 25."
    }
  },
  "required": [
    "name"
  ]
}

{
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tag": {
            "type": "string"
          },
          "size_mb": {
            "type": "number",
            "nullable": true
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "last_updated": {
            "type": "string",
            "nullable": true
          }
        }
      }
    },
    "count": {
      "type": "integer"
    },
    "image": {
      "type": "string"
    },
    "exists": {
      "type": "boolean"
    },
    "newest_first": {
      "type": "boolean",
      "description": "Tags are ordered by last update, most recent first."
    }
  }
}