Podman images (compat) API

openapi: 3.2.0
info:
  contact:
    email: podman@lists.podman.io
    name: Podman
    url: https://podman.io/community/
  description: 'This documentation describes the Podman v2.x+ RESTful API. It consists of a Docker-compatible

    API and a Libpod API providing support for Podman’s unique features such as pods.


    To start the service and keep it running for 5,000 seconds (-t 0 runs forever):


    podman system service -t 5000 &


    You can then use cURL on the socket using requests documented below.


    NOTE: if you install the package podman-docker, it will create a symbolic

    link for /run/docker.sock to /run/podman/podman.sock


    NOTE: Some fields in the API response JSON are encoded as omitempty, which means that

    if said field has a zero value, they will not be encoded in the API response. This

    is a feature to help reduce the size of the JSON responses returned via the API.


    NOTE: Due to the limitations of [go-swagger](https://github.com/go-swagger/go-swagger),

    some field values that have a complex type show up as null in the docs as well as in the

    API responses. This is because the zero value for the field type is null. The field

    description in the docs will state what type the field is expected to be for such cases.


    See podman-system-service(1) for more information.


    Quick Examples:


    ''podman info''


    curl --unix-socket /run/podman/podman.sock http://d/v6.0.0/libpod/info


    ''podman pull quay.io/containers/podman''


    curl -XPOST --unix-socket /run/podman/podman.sock -v ''http://d/v6.0.0/images/create?fromImage=quay.io%2Fcontainers%2Fpodman''


    ''podman list images''


    curl --unix-socket /run/podman/podman.sock -v ''http://d/v6.0.0/libpod/images/json'' | jq'
  license:
    name: Apache-2.0
    url: https://opensource.org/licenses/Apache-2.0
  termsOfService: https://github.com/containers/podman/blob/913caaa9b1de2b63692c9bae15120208194c9eb3/LICENSE
  title: supports a RESTful API for the Libpod library artifacts images (compat) images (compat) API
  version: 5.0.0
  x-logo:
  - url: https://raw.githubusercontent.com/containers/libpod/main/logo/podman-logo.png
  - altText: Podman logo
servers:
- url: http://podman.io/
- url: https://podman.io/
tags:
- description: Actions related to images for the compatibility endpoints
  name: images (compat)
paths:
  /build:
    post:
      description: Build an image from the given Dockerfile(s)
      operationId: ImageBuild
      parameters:
      - in: header
        name: Content-Type
        schema:
          type: string
          enum:
          - application/x-tar
          default: application/x-tar
      - in: header
        name: X-Registry-Config
        schema:
          type: string
      - description: 'Path within the build context to the `Dockerfile`.

          This is ignored if remote is specified and points to an external `Dockerfile`.

          '
        in: query
        name: dockerfile
        schema:
          type: string
          default: Dockerfile
      - description: A name and optional tag to apply to the image in the `name:tag` format. If you omit the tag, the default latest value is assumed. You can provide several t parameters.
        in: query
        name: t
        schema:
          type: string
          default: latest
      - description: 'TBD Extra hosts to add to /etc/hosts

          (As of version 1.xx)

          '
        in: query
        name: extrahosts
        schema:
          type: string
      - description: 'Not to create /etc/hosts when building the image

          '
        in: query
        name: nohosts
        schema:
          type: boolean
      - description: 'A Git repository URI or HTTP/HTTPS context URI.

          If the URI points to a single text file, the file’s contents are placed

          into a file called Dockerfile and the image is built from that file. If

          the URI points to a tarball, the file is downloaded by the daemon and the

          contents therein used as the context for the build. If the URI points to a

          tarball and the dockerfile parameter is also specified, there must be a file

          with the corresponding path inside the tarball.

          (As of version 1.xx)

          '
        in: query
        name: remote
        schema:
          type: string
      - description: 'Number of times to retry in case of failure when performing push/pull.

          '
        in: query
        name: retry
        schema:
          type: integer
          default: 3
      - description: 'Delay between retries in case of push/pull failures.

          '
        in: query
        name: retry-delay
        schema:
          type: string
          default: 2s
      - description: 'Suppress verbose build output

          '
        in: query
        name: q
        schema:
          type: boolean
          default: false
      - description: 'Do not use the cache when building the image

          (As of version 1.xx)

          '
        in: query
        name: nocache
        schema:
          type: boolean
          default: false
      - description: 'JSON array of images used to build cache resolution

          (As of version 1.xx)

          '
        in: query
        name: cachefrom
        schema:
          type: string
      - description: 'Attempt to pull the image even if an older image exists locally

          (As of version 1.xx)

          '
        in: query
        name: pull
        schema:
          type: boolean
          default: false
      - description: 'Remove intermediate containers after a successful build

          (As of version 1.xx)

          '
        in: query
        name: rm
        schema:
          type: boolean
          default: true
      - description: 'Always remove intermediate containers, even upon failure

          (As of version 1.xx)

          '
        in: query
        name: forcerm
        schema:
          type: boolean
          default: false
      - description: 'Memory is the upper limit (in bytes) on how much memory running containers can use

          (As of version 1.xx)

          '
        in: query
        name: memory
        schema:
          type: integer
      - description: 'MemorySwap limits the amount of memory and swap together

          (As of version 1.xx)

          '
        in: query
        name: memswap
        schema:
          type: integer
      - description: 'CPUShares (relative weight

          (As of version 1.xx)

          '
        in: query
        name: cpushares
        schema:
          type: integer
      - description: 'CPUSetCPUs in which to allow execution (0-3, 0,1)

          (As of version 1.xx)

          '
        in: query
        name: cpusetcpus
        schema:
          type: string
      - description: 'CPUPeriod limits the CPU CFS (Completely Fair Scheduler) period

          (As of version 1.xx)

          '
        in: query
        name: cpuperiod
        schema:
          type: integer
      - description: 'CPUQuota limits the CPU CFS (Completely Fair Scheduler) quota

          (As of version 1.xx)

          '
        in: query
        name: cpuquota
        schema:
          type: integer
      - description: 'JSON map of string pairs denoting build-time variables.

          For example, the build argument `Foo` with the value of `bar` would be encoded in JSON as `["Foo":"bar"]`.


          For example, buildargs={"Foo":"bar"}.


          Note(s):

          * This should not be used to pass secrets.

          * The value of buildargs should be URI component encoded before being passed to the API.


          (As of version 1.xx)

          '
        in: query
        name: buildargs
        schema:
          type: string
      - description: 'ShmSize is the "size" value to use when mounting an shmfs on the container''s /dev/shm directory.

          Default is 64MB

          (As of version 1.xx)

          '
        in: query
        name: shmsize
        schema:
          type: integer
          default: 67108864
      - description: 'Silently ignored.

          Squash the resulting images layers into a single layer

          (As of version 1.xx)

          '
        in: query
        name: squash
        schema:
          type: boolean
          default: false
      - description: 'Preserve intermediate stage images instead of removing them after the build completes.

          By default, they are removed to save space.

          However, they can be useful for debugging multi-stage builds or reusing stages in subsequent builds.

          '
        in: query
        name: save-stages
        schema:
          type: boolean
          default: false
      - description: 'Add metadata labels to all intermediate stage images of a multistage build, including the final image.

          If set to true, save-stages must also be set to true.

          If enabled, the labels ''io.buildah.stage.name'' and ''io.buildah.stage.base'' will be added.

          '
        in: query
        name: stage-labels
        schema:
          type: boolean
          default: false
      - description: 'JSON map of key, value pairs to set as labels on the new image

          (As of version 1.xx)

          '
        in: query
        name: labels
        schema:
          type: string
      - description: "Sets the networking mode for the run commands during build.\nSupported standard values are:\n  * `bridge` limited to containers within a single host, port mapping required for external access\n  * `host` no isolation between host and containers on this network\n  * `none` disable all networking for this container\n  * container:<nameOrID> share networking with given container\n  ---All other values are assumed to be a custom network's name\n(As of version 1.xx)\n"
        in: query
        name: networkmode
        schema:
          type: string
          default: bridge
      - description: 'Platform format os[/arch[/variant]]

          Can be comma separated list for multi arch builds.

          (As of version 1.xx)

          '
        in: query
        name: platform
        schema:
          type: string
      - description: 'Target build stage

          (As of version 1.xx)

          '
        in: query
        name: target
        schema:
          type: string
      - description: 'output configuration TBD

          (As of version 1.xx)

          '
        in: query
        name: outputs
        schema:
          type: string
      responses:
        '200':
          description: OK (As of version 1.xx)
          content:
            application/json:
              schema:
                properties:
                  stream:
                    description: output from build process
                    example: '(build details...)

                      Successfully built 8ba084515c724cbf90d447a63600c0a6

                      Successfully tagged your_image:latest

                      '
                    type: string
                required:
                - stream
                type: object
        '400':
          $ref: '#/components/responses/badParamError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Build image
      tags:
      - images (compat)
      requestBody:
        content:
          application/json:
            schema:
              format: binary
              type: string
          application/x-tar:
            schema:
              format: binary
              type: string
        description: 'A tar archive compressed with one of the following algorithms:

          identity (no compression), gzip, bzip2, xz.

          '
  /images/{name}:
    delete:
      description: Delete an image from local storage
      operationId: ImageDelete
      parameters:
      - description: name or ID of image to delete
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Remove the image even if it is being used by stopped containers or has other tags
        in: query
        name: force
        schema:
          type: boolean
      - description: do not remove dangling parent images
        in: query
        name: noprune
        schema:
          type: boolean
      - description: Ignore if a specified image does not exist and do not throw an error.
        in: query
        name: ignore
        schema:
          type: boolean
          default: false
      responses:
        '200':
          $ref: '#/components/responses/imageDeleteResponse'
        '404':
          $ref: '#/components/responses/imageNotFound'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Remove Image
      tags:
      - images (compat)
  /images/{name}/get:
    get:
      description: Export an image in tarball format
      operationId: ImageGet
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: no error
          content:
            application/x-tar:
              schema:
                format: binary
                type: string
        '500':
          $ref: '#/components/responses/internalError'
      summary: Export an image
      tags:
      - images (compat)
  /images/{name}/history:
    get:
      description: Return parent layers of an image.
      operationId: ImageHistory
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/history'
        '404':
          $ref: '#/components/responses/imageNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: History of an image
      tags:
      - images (compat)
  /images/{name}/json:
    get:
      description: Return low-level information about an image.
      operationId: ImageInspect
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/imageInspect'
        '404':
          $ref: '#/components/responses/imageNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Inspect an image
      tags:
      - images (compat)
  /images/{name}/push:
    post:
      description: Push an image to a container registry
      operationId: ImagePush
      parameters:
      - description: Name of image to push.
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: The tag to associate with the image on the registry.
        in: query
        name: tag
        schema:
          type: string
      - description: All indicates whether to push all images related to the image list
        in: query
        name: all
        schema:
          type: boolean
      - description: Use compression on image.
        in: query
        name: compress
        schema:
          type: boolean
      - description: Allows for pushing the image to a different destination than the image refers to.
        in: query
        name: destination
        schema:
          type: string
      - description: Manifest type (oci, v2s1, or v2s2) to use when pushing an image. Default is manifest type of source, with fallbacks.
        in: query
        name: format
        schema:
          type: string
      - description: Require TLS verification.
        in: query
        name: tlsVerify
        schema:
          type: boolean
          default: true
      - description: A base64-encoded auth configuration.
        in: header
        name: X-Registry-Auth
        schema:
          type: string
      responses:
        '200':
          description: no error
          content:
            application/json:
              schema:
                format: binary
                type: string
        '404':
          $ref: '#/components/responses/imageNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Push Image
      tags:
      - images (compat)
  /images/{name}/tag:
    post:
      description: Tag an image so that it becomes part of a repository.
      operationId: ImageTag
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: the repository to tag in
        in: query
        name: repo
        schema:
          type: string
      - description: the name of the new tag
        in: query
        name: tag
        schema:
          type: string
      responses:
        '201':
          description: no error
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/imageNotFound'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Tag an image
      tags:
      - images (compat)
  /images/create:
    post:
      description: Create an image by either pulling it from a registry or importing it.
      operationId: ImageCreate
      parameters:
      - description: A base64-encoded auth configuration.
        in: header
        name: X-Registry-Auth
        schema:
          type: string
      - description: Name of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. The pull is cancelled if the HTTP connection is closed.
        in: query
        name: fromImage
        schema:
          type: string
      - description: Source to import. The value may be a URL from which the image can be retrieved or - to read the image from the request body. This parameter may only be used when importing an image
        in: query
        name: fromSrc
        schema:
          type: string
      - description: Repository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.
        in: query
        name: repo
        schema:
          type: string
      - description: Tag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.
        in: query
        name: tag
        schema:
          type: string
      - description: Set commit message for imported image.
        in: query
        name: message
        schema:
          type: string
      - description: Platform in the format os[/arch[/variant]]
        in: query
        name: platform
        schema:
          type: string
      - description: Number of times to retry in case of failure when performing pull.
        in: query
        name: retry
        schema:
          type: integer
      - description: Delay between retries in case of pull failures.
        in: query
        name: retryDelay
        schema:
          type: string
      responses:
        '200':
          description: no error
          content:
            application/json:
              schema:
                format: binary
                type: string
        '404':
          $ref: '#/components/responses/imageNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Create an image
      tags:
      - images (compat)
      requestBody:
        content:
          text/plain:
            schema:
              format: binary
              type: string
          application/octet-stream:
            schema:
              format: binary
              type: string
        description: Image content if fromSrc parameter was used
  /images/get:
    get:
      description: Get a tarball containing all images and metadata for several image repositories
      operationId: ImageGetAll
      parameters:
      - description: one or more image names or IDs comma separated
        in: query
        name: names
        required: true
        schema:
          type: string
      responses:
        '200':
          description: no error
          content:
            application/json:
              schema:
                format: binary
                type: string
        '500':
          $ref: '#/components/responses/internalError'
      summary: Export several images
      tags:
      - images (compat)
  /images/json:
    get:
      description: Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.
      operationId: ImageList
      parameters:
      - description: Show all images. Only images from a final layer (no children) are shown by default.
        in: query
        name: all
        schema:
          type: boolean
          default: false
      - description: 'JSON-encoded string containing filters as a `map[string][]string` to process on the images list. Available filters:

          - `before`=(`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`)

          - `dangling=true`

          - `label=key` or `label="key=value"` of an image label

          - `reference`=(`<image-name>[:<tag>]`)

          - `since`=(`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`)

          '
        in: query
        name: filters
        schema:
          type: string
      - description: Not supported
        in: query
        name: digests
        schema:
          type: boolean
          default: false
      - description: Compute and show shared size as a SharedSize field on each image.
        in: query
        name: shared-size
        schema:
          type: boolean
          default: false
      responses:
        '200':
          $ref: '#/components/responses/imageList'
        '500':
          $ref: '#/components/responses/internalError'
      summary: List Images
      tags:
      - images (compat)
  /images/load:
    post:
      description: Load a set of images and tags into a repository.
      operationId: ImageLoad
      parameters:
      - description: not supported
        in: query
        name: quiet
        schema:
          type: boolean
      responses:
        '200':
          description: no error
        '500':
          $ref: '#/components/responses/internalError'
      summary: Import image
      tags:
      - images (compat)
      requestBody:
        content:
          application/json:
            schema:
              type: string
          application/x-tar:
            schema:
              type: string
        description: tarball of container image
  /images/prune:
    post:
      description: Remove images from local storage that are not being used by a container
      operationId: ImagePrune
      parameters:
      - description: "filters to apply to image pruning, encoded as JSON (map[string][]string). Available filters:\n  - `dangling=<boolean>` When set to `true` (or `1`), prune only\n     unused *and* untagged images. When set to `false`\n     (or `0`), all unused images are pruned.\n  - `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.\n  - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels.\n"
        in: query
        name: filters
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/imageDeleteResponse'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Prune unused images
      tags:
      - images (compat)
  /images/search:
    get:
      description: Search registries for an image
      operationId: ImageSearch
      parameters:
      - description: term to search
        in: query
        name: term
        schema:
          type: string
      - description: maximum number of results
        in: query
        name: limit
        schema:
          type: integer
          default: 25
      - description: 'JSON-encoded string containing filters as a `map[string][]string` to process on the images list. Available filters:

          - `is-automated=(true|false)`

          - `is-official=(true|false)`

          - `stars=<number>` Matches images that have at least ''number'' stars.

          '
        in: query
        name: filters
        schema:
          type: string
      - description: Require HTTPS and verify signatures when contacting registries.
        in: query
        name: tlsVerify
        schema:
          type: boolean
          default: true
      - description: list the available tags in the repository
        in: query
        name: listTags
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/registrySearchResponse'
        '400':
          $ref: '#/components/responses/badParamError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Search images
      tags:
      - images (compat)
components:
  schemas:
    Digest:
      description: 'The following is an example of the contents of Digest types:


        sha256:7173b809ca12ec5dee4506cd86be934c4596dd234ee82c0662eac04a8c2c71dc


        This allows to abstract the digest behind this type and work only in those

        terms.'
      title: 'Digest allows simple protection of hex formatted digest strings, prefixed

        by their algorithm. Strings of type Digest have some guarantee of being in

        the correct format and it provides quick access to the components of a

        digest string.'
      type: string
      x-go-package: github.com/opencontainers/go-digest
    SignatureTimestamp:
      properties:
        Timestamp:
          format: date-time
          type: string
        Type:
          $ref: '#/components/schemas/SignatureTimestampType'
        URI:
          type: string
      title: SignatureTimestamp contains information about a verified signed timestamp for an image signature.
      type: object
      x-go-package: github.com/moby/moby/api/types/image
    ManifestKind:
      type: string
      x-go-package: github.com/moby/moby/api/types/image
    BuildIdentity:
      properties:
        CreatedAt:
          description: CreatedAt is the time when the build ran.
          format: date-time
          type: string
        Ref:
          description: 'Ref is the identifier for the build request. This reference can be used to

            look up the build details in BuildKit history API.'
          type: string
      title: BuildIdentity contains build reference information if image was created via build.
      type: object
      x-go-package: github.com/moby/moby/api/types/image
    SignatureType:
      title: SignatureType is the type of signature format.
      type: string
      x-go-package: github.com/moby/moby/api/types/image
    Metadata:
      properties:
        LastTagTime:
          description: LastTagTime is the date and time at which the image was last tagged.
          format: date-time
          type: string
      title: Metadata contains engine-local data about the image.
      type: object
      x-go-package: github.com/moby/moby/api/types/image
    ImageInspect:
      properties:
        Architecture:
          description: Architecture is the hardware CPU architecture that the image runs on.
          type: string
        Author:
          description: 'Author is the name of the author that was specified when committing the

            image, or as specified through MAINTAINER (deprecated) in the Dockerfile.

            This field is omitted if not set.'
          type: string
        Comment:
          description: 'Comment is an optional message that can be set when committing or

            importing the image. This field is omitted if not set.'
          type: string
        Config:
          $ref: '#/components/schemas/DockerOCIImageConfig'
        Container:
          description: 'When you embed a struct, the fields of the embedded struct are "promoted" to the outer struct.

            If a field in the outer struct has the same name as a field in the embedded struct,

            the outer struct''s field will shadow or override the embedded one allowing for a clean way to

            hide fields from the swagger spec that still exist in the libraries struct.'
          type: string
        ContainerConfig:
          $ref: '#/components/schemas/Config'
        Created:
          description: 'Created is the date and time at which the image was created, formatted in

            RFC 3339 nano-seconds (time.RFC3339Nano).


            This information is only available if present in the image,

            and omitted otherwise.'
          type: string
        Descriptor:
          $ref: '#/components/schemas/Descriptor'
        DockerVersion:
          type: string
        GraphDriver:
          $ref: '#/components/schemas/DriverData'
        Id:
          description: 'ID is the content-addressable ID of an image.


            This identifier is a content-addressable digest calculated from the

            image''s configuration (which includes the digests of layers used by

            the image).


            Note that this digest differs from the `RepoDigests` below, which

            holds digests of image manifests that reference the image.'
          type: string
          x-go-name: ID
        Identity:
          $ref: '#/components/schemas/Identity'
        Manifests:
          description: 'Manifests is a list of image manifests available in this image. It

            provides a more detailed view of the platform-specific image manifests or

            other image-attached data like build attestations.


            Only available if the daemon provides a multi-platform image store, the client

            requests manifests AND does not request a specific platform.


            WARNING: This is experimental and may change at any time without any backward

            compatibility.'
          items:
            $ref: '#/components/schemas/ManifestSummary'
          type: array
        Metadata:
          $ref: '#/components/schemas/Metadata'
        Os:
          description: OS is the Operating System the image is built to run on.
          type: string
        OsVersion:
          description: 'OsVersion is the version of the Operating System the image is built to

            run on (especially for Windows).'
          type: string
        Parent:
          type: string
        RepoDigests:
          description: 'RepoDigests is a list of content-addressable digests of locally available

            image manifests that the image is referenced from. Multiple manifests can

            refer to the same image.


            These digests are usually only available if the image was either pulled

            from a registry, or if the image was pushed to a registry, which is when

            the manifest is generated and its digest calculated.'
          items:
            type: string
          type: array
        RepoTags:
          description: 'RepoTags is a list of image names/tags in the local image cache that

            reference this image.


            Multiple image tags can refer to the same image, and this list may be

            empty if no tags reference the image, in which case the image is

            "untagged", in which case it can still be referenced by its ID.'
          items:
            type: string
          type: array
        RootFS:
          $ref: '#/components/schemas/RootFS'
        Size:
          description: Size is the total size of the image including all layers it is composed of.
          format: int64
          type: integer
        Variant:
          description: Variant is the CPU architecture variant (presently ARM-only).
          type: string
        VirtualSize:
          format: int64
          type: integer
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/api/handlers
    PullIdentity:
      description: If image was pulled via mirror, this contains the original repository location.
      properties:
        Repository:
          description: Re

# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/podman/refs/heads/main/openapi/podman-images-compat-api-openapi.yml