Podman images (compat) API
Actions related to images for the compatibility endpoints
Actions related to images for the compatibility endpoints
swagger: '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) API
version: 5.0.0
x-logo:
- url: https://raw.githubusercontent.com/containers/libpod/main/logo/podman-logo.png
- altText: Podman logo
host: podman.io
basePath: /
schemes:
- http
- https
consumes:
- application/json
- application/x-tar
produces:
- application/json
- application/octet-stream
- text/plain
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:
- default: application/x-tar
enum:
- application/x-tar
in: header
name: Content-Type
type: string
- in: header
name: X-Registry-Config
type: string
- default: Dockerfile
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
type: string
- default: latest
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
type: string
- description: 'TBD Extra hosts to add to /etc/hosts
(As of version 1.xx)
'
in: query
name: extrahosts
type: string
- description: 'Not to create /etc/hosts when building the image
'
in: query
name: nohosts
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
type: string
- default: 3
description: 'Number of times to retry in case of failure when performing push/pull.
'
in: query
name: retry
type: integer
- default: 2s
description: 'Delay between retries in case of push/pull failures.
'
in: query
name: retry-delay
type: string
- default: false
description: 'Suppress verbose build output
'
in: query
name: q
type: boolean
- default: false
description: 'Do not use the cache when building the image
(As of version 1.xx)
'
in: query
name: nocache
type: boolean
- description: 'JSON array of images used to build cache resolution
(As of version 1.xx)
'
in: query
name: cachefrom
type: string
- default: false
description: 'Attempt to pull the image even if an older image exists locally
(As of version 1.xx)
'
in: query
name: pull
type: boolean
- default: true
description: 'Remove intermediate containers after a successful build
(As of version 1.xx)
'
in: query
name: rm
type: boolean
- default: false
description: 'Always remove intermediate containers, even upon failure
(As of version 1.xx)
'
in: query
name: forcerm
type: boolean
- 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
type: integer
- description: 'MemorySwap limits the amount of memory and swap together
(As of version 1.xx)
'
in: query
name: memswap
type: integer
- description: 'CPUShares (relative weight
(As of version 1.xx)
'
in: query
name: cpushares
type: integer
- description: 'CPUSetCPUs in which to allow execution (0-3, 0,1)
(As of version 1.xx)
'
in: query
name: cpusetcpus
type: string
- description: 'CPUPeriod limits the CPU CFS (Completely Fair Scheduler) period
(As of version 1.xx)
'
in: query
name: cpuperiod
type: integer
- description: 'CPUQuota limits the CPU CFS (Completely Fair Scheduler) quota
(As of version 1.xx)
'
in: query
name: cpuquota
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
type: string
- default: 67108864
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
type: integer
- default: false
description: 'Silently ignored.
Squash the resulting images layers into a single layer
(As of version 1.xx)
'
in: query
name: squash
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
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
type: boolean
- description: 'JSON map of key, value pairs to set as labels on the new image
(As of version 1.xx)
'
in: query
name: labels
type: string
- default: bridge
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
type: string
- description: 'Platform format os[/arch[/variant]]
Can be comma separated list for multi arch builds.
(As of version 1.xx)
'
in: query
name: platform
type: string
- description: 'Target build stage
(As of version 1.xx)
'
in: query
name: target
type: string
- description: 'output configuration TBD
(As of version 1.xx)
'
in: query
name: outputs
type: string
- description: 'A tar archive compressed with one of the following algorithms:
identity (no compression), gzip, bzip2, xz.
'
in: body
name: inputStream
schema:
format: binary
type: string
produces:
- application/json
responses:
'200':
description: OK (As of version 1.xx)
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: '#/responses/badParamError'
'500':
$ref: '#/responses/internalError'
summary: Build image
tags:
- images (compat)
/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
type: string
- description: Remove the image even if it is being used by stopped containers or has other tags
in: query
name: force
type: boolean
- description: do not remove dangling parent images
in: query
name: noprune
type: boolean
- default: false
description: Ignore if a specified image does not exist and do not throw an error.
in: query
name: ignore
type: boolean
produces:
- application/json
responses:
'200':
$ref: '#/responses/imageDeleteResponse'
'404':
$ref: '#/responses/imageNotFound'
'409':
$ref: '#/responses/conflictError'
'500':
$ref: '#/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
type: string
produces:
- application/x-tar
responses:
'200':
description: no error
schema:
format: binary
type: string
'500':
$ref: '#/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
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/history'
'404':
$ref: '#/responses/imageNotFound'
'500':
$ref: '#/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
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/imageInspect'
'404':
$ref: '#/responses/imageNotFound'
'500':
$ref: '#/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
type: string
- description: The tag to associate with the image on the registry.
in: query
name: tag
type: string
- description: All indicates whether to push all images related to the image list
in: query
name: all
type: boolean
- description: Use compression on image.
in: query
name: compress
type: boolean
- description: Allows for pushing the image to a different destination than the image refers to.
in: query
name: destination
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
type: string
- default: true
description: Require TLS verification.
in: query
name: tlsVerify
type: boolean
- description: A base64-encoded auth configuration.
in: header
name: X-Registry-Auth
type: string
produces:
- application/json
responses:
'200':
description: no error
schema:
format: binary
type: string
'404':
$ref: '#/responses/imageNotFound'
'500':
$ref: '#/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
type: string
- description: the repository to tag in
in: query
name: repo
type: string
- description: the name of the new tag
in: query
name: tag
type: string
produces:
- application/json
responses:
'201':
description: no error
'400':
$ref: '#/responses/badParamError'
'404':
$ref: '#/responses/imageNotFound'
'409':
$ref: '#/responses/conflictError'
'500':
$ref: '#/responses/internalError'
summary: Tag an image
tags:
- images (compat)
/images/create:
post:
consumes:
- text/plain
- application/octet-stream
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
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
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
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
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
type: string
- description: Set commit message for imported image.
in: query
name: message
type: string
- description: Platform in the format os[/arch[/variant]]
in: query
name: platform
type: string
- description: Number of times to retry in case of failure when performing pull.
in: query
name: retry
type: integer
- description: Delay between retries in case of pull failures.
in: query
name: retryDelay
type: string
- description: Image content if fromSrc parameter was used
in: body
name: inputImage
schema:
format: binary
type: string
produces:
- application/json
responses:
'200':
description: no error
schema:
format: binary
type: string
'404':
$ref: '#/responses/imageNotFound'
'500':
$ref: '#/responses/internalError'
summary: Create an image
tags:
- images (compat)
/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
type: string
produces:
- application/json
responses:
'200':
description: no error
schema:
format: binary
type: string
'500':
$ref: '#/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:
- default: false
description: Show all images. Only images from a final layer (no children) are shown by default.
in: query
name: all
type: boolean
- 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
type: string
- default: false
description: Not supported
in: query
name: digests
type: boolean
- default: false
description: Compute and show shared size as a SharedSize field on each image.
in: query
name: shared-size
type: boolean
produces:
- application/json
responses:
'200':
$ref: '#/responses/imageList'
'500':
$ref: '#/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
type: boolean
- description: tarball of container image
in: body
name: request
schema:
type: string
produces:
- application/json
responses:
'200':
description: no error
'500':
$ref: '#/responses/internalError'
summary: Import image
tags:
- images (compat)
/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
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/imageDeleteResponse'
'500':
$ref: '#/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
type: string
- default: 25
description: maximum number of results
in: query
name: limit
type: integer
- 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
type: string
- default: true
description: Require HTTPS and verify signatures when contacting registries.
in: query
name: tlsVerify
type: boolean
- description: list the available tags in the repository
in: query
name: listTags
type: boolean
produces:
- application/json
responses:
'200':
$ref: '#/responses/registrySearchResponse'
'400':
$ref: '#/responses/badParamError'
'500':
$ref: '#/responses/internalError'
summary: Search images
tags:
- images (compat)
definitions:
HealthConfig:
title: HealthConfig holds configuration settings for the HEALTHCHECK feature.
type: object
x-go-package: github.com/moby/moby/api/types/container
DriverData:
description: DriverData handles the data for a storage driver
properties:
Data:
additionalProperties:
type: string
description: 'Low-level storage metadata, provided as key/value pairs.
This information is driver-specific, and depends on the storage-driver
in use, and should be used for informational purposes only.'
example:
MergedDir: /var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged
UpperDir: /var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff
WorkDir: /var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work
type: object
Name:
description: Name of the storage driver.
example: overlay2
type: string
required:
- Data
- Name
type: object
x-go-package: go.podman.io/podman/v6/libpod/define
HealthcheckConfig:
properties:
Interval:
$ref: '#/definitions/Duration'
Retries:
description: 'Retries is the number of consecutive failures needed to consider a container as unhealthy.
Zero means inherit.'
format: int64
type: integer
StartInterval:
$ref: '#/definitions/Duration'
StartPeriod:
$ref: '#/definitions/Duration'
Test:
description: 'Test is the test to perform to check that the container is healthy.
An empty slice means to inherit the default.
The options are:
{} : inherit healthcheck
{"NONE"} : disable healthcheck
{"CMD", args...} : exec arguments directly
{"CMD-SHELL", command} : run command with system''s default shell'
items:
type: string
type: array
Timeout:
$ref: '#/definitions/Duration'
title: HealthcheckConfig holds configuration settings for the HEALTHCHECK feature.
type: object
x-go-package: github.com/moby/docker-image-spec/specs-go/v1
ErrorModel:
description: ErrorModel is used in remote connections with podman
properties:
cause:
description: API root cause formatted for automated parsing
example: API root cause
type: string
x-go-name: Because
message:
description: human error message, formatted for a human to read
example: human error message
type: string
x-go-name: Message
response:
description: HTTP response code
format: int64
minimum: 400
type: integer
x-go-name: ResponseCode
type: object
x-go-package: go.podman.io/podman/v6/pkg/errorhandling
Descriptor:
description: 'This structure provides `application/vnd.oci.descriptor.v1+json` mediatype
when marshalled to JSON.'
properties:
annotations:
additionalProperties:
type: string
description: Annotations contains arbitrary metadata relating to the targeted content.
type: object
x-go-name: Annotations
artifactType:
description: ArtifactType is the IANA media type of this artifact.
type: string
x-go-name: ArtifactType
data:
description: 'Data is an embedding of the targeted content. This is encoded as a base64
string when marshalled to JSON (automatically, by encoding/json). If
present, Data can be used directly to avoid fetching the targeted content.'
items:
format: uint8
type: integer
type: array
x-go-name: Data
digest:
$ref: '#/definitions/Digest'
mediaType:
description: MediaType is the media type of the object this schema refers to.
type: string
x-go-name: MediaType
platform:
$ref: '#/definitions/Platform'
size:
description: Size specifies the size in bytes of the blob.
format: int64
type: integer
x-go-name: Size
urls:
description: URLs specifies a list of URLs from which this object MAY be downloaded
items:
type: string
type: array
x-go-name: URLs
title: Descriptor describes the disposition of targeted content.
type: object
x-go-package: github.com/opencontainers/image-spec/specs-go/v1
SignatureIdentity:
properties:
DockerReference:
description: 'DockerReference is the Docker image reference associated with the signature.
This is an optional field only present in older hashedrecord signatures.'
type: string
Error:
description: 'Error contains error information if signature verification failed.
Other fields will be empty in this case.'
type: string
KnownSigner:
$ref: '#/definitions/KnownSignerIdentity'
Name:
description: Name is a textual description summarizing the type of signature.
type: string
SignatureType:
$ref: '#/definitions/SignatureType'
Signer:
$ref: '#/definitions/SignerIdentity'
Timestamps:
description: Timestamps contains a list of verified signed timestamps for the signature.
items:
$ref: '#/definitions/SignatureTimestamp'
type: array
Warnings:
description: 'Warnings contains any warnings that occurred during signature verification.
For example, if there was no internet connectivity and cached trust roots were used.
Warning does not indicate a failed verification but may point to configuration issues.'
items:
type: string
type: array
title: SignatureIdentity contains the properties of verified signatures for the image.
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
SignerIdentity:
description: '[certificate.Summary]: https://pkg.go.dev/github.com/sigstore/sigstore-go/pkg/fulcio/certificate#Summary'
properties:
BuildConfigDigest:
description: Immutable reference to the specific version of the top-level/initiating build instructions.
type: string
BuildConfigURI:
description: Build Config URL to the top-level/initiating build instructions.
type: string
BuildSignerDigest:
description: Immutable reference to the specific version of the build instructions that is responsible for signing.
type: string
BuildSignerURI:
description: Reference to specific build instructions that are responsible for signing.
type: string
BuildTrigger:
description: Event or action that initiated the build.
type: string
CertificateIssuer:
type: string
Issuer:
description: 'The OIDC issuer. Should match `iss` claim of ID token or, in the case of
a federated login like Dex it should match the issuer URL of the
upstream issuer. The issuer is not set the extensions are invalid and
will fail to render.'
type: string
RunInvocationURI:
description: Run Invocation URL to uniquely identify the build execution.
type: string
RunnerEnvironment:
description: Specifies whether the build took place in platform-hosted cloud infrastructure or customer/self-hosted infrastructure.
type: string
SourceRepositoryDigest:
description: Immutable reference to a specific version of the source code that the build was based upon.
type: string
SourceRepositoryIdentifier:
description: Immutable identifier for the source repository the workflow was based upon.
type: string
SourceRepositoryOwnerIdentifier:
description: Immutable identifier for the owner of the source repository that the workflow was based upon.
type: string
SourceRepositoryOwnerURI:
description: Source repository owner URL of the owner of the source repository that the build was based on.
type: string
SourceRepositoryRef:
description: Source Repository Ref that the build run was based upon.
type: string
SourceRepositoryURI:
description: Source repository URL that the build was based on.
type: string
SourceRepositoryVisibilityAtSigning:
description: Source repository visibility at the time of signing the certificate.
type: string
SubjectAlternativeName:
type: str
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/podman/refs/heads/main/openapi/podman-images-compat-api-openapi.yml