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 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
name: images
paths:
/libpod/build:
post:
description: Build an image from the given Dockerfile(s)
operationId: ImageBuildLibpod
parameters:
- default: application/x-tar
enum:
- application/x-tar
- multipart/form-data
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
- default: false
description: 'Instead of building for a set of platforms specified using the platform option, inspect the build''s base images,
and build for all of the platforms that are available. Stages that use *scratch* as a starting point can not be inspected,
so at least one non-*scratch* stage must be present for detection to work usefully.
'
in: query
name: allplatforms
type: boolean
- default: []
description: "Additional build contexts for builds that require more than one context.\nEach additional context must be specified as a key-value pair in the format \"name=value\".\n\nThe value can be specified in two formats:\n- URL context: Use the prefix \"url:\" followed by a URL to a tar archive\n Example: \"mycontext=url:https://example.com/context.tar\"\n- Image context: Use the prefix \"image:\" followed by an image reference\n Example: \"mycontext=image:alpine:latest\" or \"mycontext=image:docker.io/library/ubuntu:22.04\"\n\nLocal contexts are provided via multipart/form-data upload. When using multipart/form-data,\ninclude additional build contexts as separate form fields with names prefixed by \"build-context-\".\nFor example, a local context named \"mycontext\" should be uploaded as a tar file in a field\nnamed \"build-context-mycontext\".\n\n(As of version 5.6.0)\n"
in: query
items:
type: string
name: additionalbuildcontexts
type: array
- 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: false
description: 'Suppress verbose build output
'
in: query
name: q
type: boolean
- default: false
description: 'Contents of volume locations to be modified on ADD or COPY only
(As of Podman version v5.2)
'
in: query
name: compatvolumes
type: boolean
- default: true
description: 'Add an "org.opencontainers.image.created" annotation to the
image.
(As of Podman version v5.6)
'
in: query
name: createdannotation
type: boolean
- description: 'Timestamp to use for newly-added history entries and the image''s
creation date.
(As of Podman version v5.6)
'
in: query
name: sourcedateepoch
type: number
- default: false
description: 'If sourcedateepoch is set, force new content added in layers to
have timestamps no later than the sourcedateepoch date.
(As of Podman version v5.6)
'
in: query
name: rewritetimestamp
type: boolean
- description: 'Timestamp to use for newly-added history entries, the image''s
creation date, and for new content added in layers.
'
in: query
name: timestamp
type: number
- default: true
description: 'Inherit the labels from the base image or base stages
(As of Podman version v5.5)
'
in: query
name: inheritlabels
type: boolean
- default: true
description: 'Inherit the annotations from the base image or base stages
(As of Podman version v5.6)
'
in: query
name: inheritannotations
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
- 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
- description: Add an intermediate image *label* (e.g. label=*value*) to the intermediate image metadata.
in: query
items:
type: string
name: layerLabel
type: array
- default: true
description: 'Cache intermediate layers during build.
(As of version 1.xx)
'
in: query
name: layers
type: boolean
- 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]]
(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: 'Inject http proxy environment variables into container
(As of version 2.0.0)
'
in: query
name: httpproxy
type: boolean
- description: Unset environment variables from the final image.
in: query
items:
type: string
name: unsetenv
type: array
- description: Unset the image label, causing the label not to be inherited from the base image.
in: query
items:
type: string
name: unsetlabel
type: array
- description: 'Unset the image annotation, causing the annotation not to be inherited from the base image.
(As of Podman version v5.6)
'
in: query
items:
type: string
name: unsetannotation
type: array
- description: Extra volumes that should be mounted in the build container.
in: query
items:
type: string
name: volume
type: array
- description: 'Add the image to the specified manifest list. Creates a manifest list if it does not exist.
'
in: query
name: manifest
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...)
'
type: string
required:
- stream
type: object
'400':
$ref: '#/responses/badParamError'
'500':
$ref: '#/responses/internalError'
summary: Build image
tags:
- images
/libpod/images/{name}:
delete:
description: Remove an image from the local storage.
operationId: ImageDeleteLibpod
parameters:
- description: name or ID of image to remove
in: path
name: name
required: true
type: string
- description: remove the image even if used by containers or has other tags
in: query
name: force
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
- description: Resolve to a manifest list instead of an image.
in: query
name: lookupManifest
type: boolean
produces:
- application/json
responses:
'200':
$ref: '#/responses/imagesRemoveResponseLibpod'
'400':
$ref: '#/responses/badParamError'
'404':
$ref: '#/responses/imageNotFound'
'409':
$ref: '#/responses/conflictError'
'500':
$ref: '#/responses/internalError'
summary: Remove an image from the local storage.
tags:
- images
/libpod/images/{name}/changes:
get:
description: 'Returns which files in an image''s filesystem have been added, deleted, or modified. The Kind of modification can be one of:
0: Modified
1: Added
2: Deleted
'
operationId: ImageChangesLibpod
parameters:
- description: the name or id of the image
in: path
name: name
required: true
type: string
- description: specify a second layer which is used to compare against it instead of the parent layer
in: query
name: parent
type: string
- description: select what you want to match, default is all
enum:
- all
- container
- image
in: query
name: diffType
type: string
responses:
'200':
description: Array of Changes
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Report on changes to images's filesystem; adds, deletes or modifications.
tags:
- images
/libpod/images/{name}/exists:
get:
description: Check if image exists in local store
operationId: ImageExistsLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'204':
description: image exists
'404':
$ref: '#/responses/imageNotFound'
'500':
$ref: '#/responses/internalError'
summary: Image exists
tags:
- images
/libpod/images/{name}/get:
get:
description: Export an image
operationId: ImageGetLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- description: format for exported image
in: query
name: format
type: string
- description: use compression on image
in: query
name: compress
type: boolean
produces:
- application/x-tar
responses:
'200':
description: no error
schema:
format: binary
type: string
'404':
$ref: '#/responses/imageNotFound'
'500':
$ref: '#/responses/internalError'
summary: Export an image
tags:
- images
/libpod/images/{name}/history:
get:
description: Return parent layers of an image.
operationId: ImageHistoryLibpod
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
/libpod/images/{name}/json:
get:
description: Obtain low-level information about an image
operationId: ImageInspectLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/inspectImageResponseLibpod'
'404':
$ref: '#/responses/imageNotFound'
'500':
$ref: '#/responses/internalError'
summary: Inspect an image
tags:
- images
/libpod/images/{name}/push:
post:
description: Push an image to a container registry
operationId: ImagePushLibpod
parameters:
- description: Name of image to push.
in: path
name: name
required: true
type: string
- description: Allows for pushing the image to a different destination than the image refers to.
in: query
name: destination
type: string
- default: false
description: Enforce compressing the layers with the specified --compression and do not reuse differently compressed blobs on the registry.
in: query
name: forceCompressionFormat
type: boolean
- description: Compression format used to compress image layers.
in: query
name: compressionFormat
type: string
- description: Compression level used to compress image layers.
in: query
name: compressionLevel
type: integer
- default: true
description: Require TLS verification.
in: query
name: tlsVerify
type: boolean
- default: true
description: Silences extra stream data on push.
in: query
name: quiet
type: boolean
- 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
- description: All indicates whether to push all images related to the image list.
in: query
name: all
type: boolean
- description: Discard any pre-existing signatures in the image.
in: query
name: removeSignatures
type: boolean
- description: Number of times to retry push in case of failure.
in: query
name: retry
type: integer
- description: Delay between retries in case of push failures. Duration format such as "412ms", or "3.5h".
in: query
name: retryDelay
type: string
- 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
/libpod/images/{name}/resolve:
get:
description: Resolve the passed image name to a list of fully-qualified images referring to container registries.
operationId: ImageResolveLibpod
parameters:
- description: the (short) name to resolve
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'204':
description: resolved image names
'400':
$ref: '#/responses/badParamError'
'500':
$ref: '#/responses/internalError'
summary: Resolve an image (short) name
tags:
- images
/libpod/images/{name}/tag:
post:
description: Tag an image so that it becomes part of a repository.
operationId: ImageTagLibpod
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
/libpod/images/{name}/tree:
get:
description: Retrieve the image tree for the provided image name or ID
operationId: ImageTreeLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- description: show all child images and layers of the specified image
in: query
name: whatrequires
type: boolean
produces:
- application/json
responses:
'200':
$ref: '#/responses/treeResponse'
'404':
$ref: '#/responses/imageNotFound'
'500':
$ref: '#/responses/internalError'
summary: Image tree
tags:
- images
/libpod/images/{name}/untag:
post:
description: Untag an image. If not repo and tag are specified, all tags are removed from the image.
operationId: ImageUntagLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- description: the repository to untag
in: query
name: repo
type: string
- description: the name of the tag to untag
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: Untag an image
tags:
- images
/libpod/images/export:
get:
description: Export multiple images into a single object. Only `docker-archive` is currently supported.
operationId: ImageExportLibpod
parameters:
- description: format for exported image (only docker-archive is supported)
in: query
name: format
type: string
- description: references to images to export
in: query
items:
type: string
name: references
type: array
- description: use compression on image
in: query
name: compress
type: boolean
- description: accept uncompressed layers when copying OCI images
in: query
name: ociAcceptUncompressedLayers
type: boolean
produces:
- application/json
responses:
'200':
description: no error
schema:
format: binary
type: string
'404':
$ref: '#/responses/imageNotFound'
'500':
$ref: '#/responses/internalError'
summary: Export multiple images
tags:
- images
/libpod/images/import:
post:
consumes:
- application/x-tar
description: Import a previously exported tarball as an image.
operationId: ImageImportLibpod
parameters:
- default: application/x-tar
enum:
- application/x-tar
in: header
name: Content-Type
type: string
- description: 'Apply the following possible instructions to the created image: CMD | ENTRYPOINT | ENV | EXPOSE | LABEL | STOPSIGNAL | USER | VOLUME | WORKDIR. JSON encoded string'
in: query
items:
type: string
name: changes
type: array
- description: Set commit message for imported image
in: query
name: message
type: string
- description: Optional Name[:TAG] for the image
in: query
name: reference
type: string
- description: Load image from the specified URL
in: query
name: url
type: string
- description: tarball for imported image
in: body
name: upload
required: true
schema:
format: binary
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/imagesImportResponseLibpod'
'400':
$ref: '#/responses/badParamError'
'500':
$ref: '#/responses/internalError'
summary: Import image
tags:
- images
/libpod/images/json:
get:
description: Returns a list of images on the server
operationId: ImageListLibpod
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>]`)
- `id`=(`<image-id>`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
'
in: query
name: filters
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/imageListLibpod'
'500':
$ref: '#/responses/internalError'
summary: List Images
tags:
- images
/libpod/images/load:
post:
consumes:
- application/x-tar
description: Load an image (oci-archive or docker-archive) stream.
operationId: ImageLoadLibpod
parameters:
- description: tarball of container image
in: body
name: upload
required: true
schema:
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/imagesLoadResponseLibpod'
'400':
$ref: '#/responses/badParamError'
'500':
$ref: '#/responses/internalError'
summary: Load image
tags:
- images
/libpod/images/prune:
post:
description: Remove images that are not being used by a container
operationId: ImagePruneLibpod
parameters:
- default: false
description: 'Remove all images not in use by containers, not just dangling ones
'
in: query
name: all
type: boolean
- default: false
description: 'Remove images even when they are used by external containers (e.g, by build containers)
'
in: query
name: external
type: boolean
- default: false
description: 'Remove persistent build cache created by build instructions such as `--mount=type=cache`.
'
in: query
name: buildcache
type: boolean
- 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/imagesPruneLibpod'
'500':
$ref: '#/responses/internalError'
summary: Prune unused images
tags:
- images
/libpod/images/pull:
post:
description: Pull one or more images from a container registry. Error status codes can come either from the API or from the registry. Errors may be detected later even if the HTTP status 200 is returned, and in that case, the error description will be in the `error` field.
operationId: ImagePullLibpod
parameters:
- description: Mandatory reference to the image (e.g., quay.io/image/name:tag)
in: query
name: reference
type: string
- default: false
description: Silence extra stream data on pull. Cannot be used with 'compatMode' or 'pullProgress'.
in: query
name: quiet
type: boolean
- default: false
description: Return the same JSON payload as the Docker-compat endpoint. Cannot be used with 'pullProgress' or 'quiet'.
in: query
name: compatMode
type: boolean
- default: false
description: Send reports about the progress of the pull. Cannot be used with 'compatMode' or 'quiet'.
in: query
name: pullProgress
type: boolean
- description: Pull image for the specified architecture.
in: query
name: Arch
type: string
- description: Pull image for the specified operating system.
in: query
name: OS
type: string
- description: Pull image for the specified variant.
in: query
name: Variant
type: string
- description: Pull policy, "always" (default), "missing", "newer", "never".
in: query
name: policy
type: string
- default: true
description: Require TLS verification.
in: query
name: tlsVerify
type: boolean
- description: Pull all tagged images in the repository
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/podman/refs/heads/main/openapi/podman-images-api-openapi.yml