The API is currently in beta. We are looking for feedback on both the API design itself and the documentation.


Humanitec tracks source control metadata alongside versions of container images. This allows developers to easily understand what commit on what branch generated a particular image.

In most cases, Humanitec is informed about new versions of images via the CI pipeline building the image. The CI pipeline is able to provide:

  • The registry, repository, and tag for the image
  • The commit that the image was built from
  • The tag or branch that the commit was on for the build.

Image Object

  "id": "my-image",
  "source": "my-image-source",
  "builds": [
      "image": "my-registry/my-image:my-tag",
      "commit": "df1ad41807b0390a9b0eaf8688e1f5baece9d764",
      "branch": "master",
      "tags": [],
      "added_at": "2020-05-22T14:53:27Z"
  "added_at": "2020-05-18T09:21:59Z"

Image properties

Parameter Description
id ID of the image. Must conform to the Humanitec ID format. Does not have to match the image name.
source Reference to the source of the image metadata. (See Image Sources)
build Each version of an image is referred to as a build. Each image can have multiple builds.
added_at The timestamp of when the image was added to Humanitec.

Build properties

Parameter Description
image The fully qualified image path including registry, repository, and tag.
commit The unique ID from the version control system representing the version of code the image is built from.
branch [Optional] The branch from which the image was built.
tags [Optional] The tag(s) from which the image was built.
added_at The timestamp of when the build was added to Humanitec.