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: 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`=(`[:]`, `` or ``) - `dangling=true` - `label=key` or `label="key=value"` of an image label - `reference`=(`[:]`) - `id`=(``) - `since`=(`[:]`, `` or ``) ' 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=` 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=` Prune images created before this timestamp. The `` 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=`, `label==`, `label!=`, or `label!==`) 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. in: query name: allTags type: boolean - description: 'base-64 encoded auth config. Must include the following four values: username, password, email and server address OR simply just an identity token.' in: header name: X-Registry-Auth type: string produces: - application/json responses: '200': $ref: '#/responses/imagesPullResponseLibpod' '400': $ref: '#/responses/badParamError' '500': $ref: '#/responses/internalError' default: $ref: '#/responses/errorFromRegistry' summary: Pull images tags: - images /libpod/images/remove: delete: description: Remove one or more images from the storage. operationId: ImageDeleteAllLibpod parameters: - description: Images IDs or names to remove. in: query items: type: string name: images type: array - default: true description: Remove all images. in: query name: all type: boolean - description: Force image removal (including containers using the images). in: query name: force type: boolean - description: Ignore if a specified image does not exist and do not throw an error. in: query name: ignore type: boolean - description: Resolves to manifest list instead of image. in: query name: lookupManifest type: boolean produces: - application/json responses: '200': $ref: '#/responses/imagesRemoveResponseLibpod' '400': $ref: '#/responses/badParamError' '500': $ref: '#/responses/internalError' summary: Remove one or more images from the storage. tags: - images /libpod/images/scp/{name}: post: description: Copy an image from one host to another operationId: ImageScpLibpod parameters: - description: source connection/image in: path name: name required: true type: string - description: dest connection/image in: query name: destination type: string - default: false description: quiet output in: query name: quiet type: boolean produces: - application/json responses: '200': $ref: '#/responses/imagesScpResponseLibpod' '400': $ref: '#/responses/badParamError' '500': $ref: '#/responses/internalError' summary: Copy an image from one host to another tags: - images /libpod/images/search: get: description: Search registries for images operationId: ImageSearchLibpod 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=` 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 - default: false description: list the available tags in the repository in: query name: listTags type: boolean produces: - application/json responses: '200': $ref: '#/responses/registrySearchResponse' '500': $ref: '#/responses/internalError' summary: Search images tags: - images /libpod/local/build: post: description: Build an image from a local build context directory without requiring tar archive upload. The build context must already exist on the server filesystem. operationId: LocalBuildLibpod parameters: - in: header name: X-Registry-Config type: string - description: 'Absolute path to the build context directory on the server filesystem. This directory must contain all files needed for the build. ' in: query name: localcontextdir required: true type: string - default: Dockerfile description: 'Absolute 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 three 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- Local path context: Use the prefix \"localpath:\" followed by an absolute path on the server filesystem\n Example: \"mycontext=localpath:/path/to/context/dir\"\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: 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' '404': $ref: '#/responses/fileNotFound' '500': $ref: '#/responses/internalError' summary: Create image from local build context tags: - images /libpod/local/images/load: post: description: Load an image (oci-archive or docker-archive) from a file path accessible on the server. operationId: LocalImagesLibpod parameters: - description: Absolute path to the image archive file on the server filesystem in: query name: path required: true type: string produces: - application/json responses: '200': $ref: '#/responses/imagesLoadResponseLibpod' '400': $ref: '#/responses/badParamError' '404': $ref: '#/responses/imageNotFound' '500': $ref: '#/responses/internalError' summary: Load image from local path tags: - images definitions: 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 LibpodImagesRemoveReport: allOf: - $ref: '#/definitions/ImageRemoveReport' - properties: Errors: description: Image removal requires is to return data and an error. items: type: string type: array type: object description: 'LibpodImagesRemoveReport is the return type for image removal via the rest api.' x-go-package: go.podman.io/podman/v6/pkg/api/handlers 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 History: properties: author: description: Author is the author of the build point. type: string x-go-name: Author comment: description: Comment is a custom message set when creating the layer. type: string x-go-name: Comment created: description: Created is the combined date and time at which the layer was created, formatted as defined by RFC 3339, section 5.6. format: date-time type: string x-go-name: Created created_by: description: CreatedBy is the command which created the layer. type: string x-go-name: CreatedBy empty_layer: description: EmptyLayer is used to mark if the history item created a filesystem diff. type: boolean x-go-name: EmptyLayer title: History describes the history of a layer. type: object x-go-package: github.com/opencontainers/image-spec/specs-go/v1 ImagePullReport: title: ImagePullReport is the response from pulling one or more images. type: object x-go-package: go.podman.io/podman/v6/pkg/domain/entities ImageImportReport: type: object x-go-package: go.podman.io/podman/v6/pkg/domain/entities HistoryResponse: description: HistoryResponse provides details on image layers properties: Comment: type: string Created: format: int64 type: integer CreatedBy: type: string Id: type: string x-go-name: ID Size: format: int64 type: integer Tags: items: type: string type: array type: object x-go-package: go.podman.io/podman/v6/pkg/api/handlers ScpReport: properties: Id: type: string type: object x-go-package: go.podman.io/podman/v6/pkg/domain/entities/reports ImageSummary: type: object x-go-package: go.podman.io/podman/v6/pkg/domain/entities ImageRemoveReport: description: 'ImageRemoveReport is the response for removing one or more image(s) from storage and images what was untagged vs actually removed.' type: object x-go-package: go.podman.io/podman/v6/pkg/domain/entities PruneReport: description: POST "/volumes/prune" properties: Err: type: string x-go-type: error Id: type: string Size: format: uint64 type: integer title: 'PruneReport contains the response for Engine API:' type: object x-go-package: go.podman.io/podman/v6/pkg/domain/entities/reports ImageLoadReport: type: object x-go-package: go.podman.io/podman/v6/pkg/domain/entities 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 Schema2HealthConfig: description: 'Schema2HealthConfig is a HealthConfig, which holds configuration settings for the HEALTHCHECK feature, from docker/docker/api/types/container.' 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' type: object x-go-package: go.podman.io/image/v5/manifest ImageTreeReport: description: ImageTreeReport provides results from ImageEngine.Tree() type: object x-go-package: go.podman.io/podman/v6/pkg/domain/entities ImageConfig: properties: ArgsEscaped: description: 'ArgsEscaped Deprecated: This field is present only for legacy compatibility with Docker and should not be used by new image builders. It is used by Docker for Windows images to indicate that the `Entrypoint` or `Cmd` or both, contains only a single element array, that is a pre-escaped, and combined into a single string `CommandLine`. If `true` the value in `Entrypoint` or `Cmd` should be used as-is to avoid double escaping. https://github.com/opencontainers/image-spec/pull/892' type: boolean Cmd: description: Cmd defines the default arguments to the entrypoint of the container. items: type: string type: array Entrypoint: description: Entrypoint defines a list of arguments to use as the command to execute when the container starts. items: type: string type: array Env: description: Env is a list of environment variables to be used in a container. items: type: string type: array ExposedPorts: additionalProperties: type: object description: ExposedPorts a set of ports to expose from a container running this image. type: object Labels: additionalProperties: type: string description: Labels contains arbitrary metadata for the container. type: object StopSignal: description: StopSignal contains the system call signal that will be sent to the container to exit. type: string User: description: User defines the username or UID which the process in the container should run as. type: string Volumes: additionalProperties: type: object description: Volumes is a set of directories describing where the process is likely write data specific to a container instance. type: object WorkingDir: description: WorkingDir sets the current working directory of the entrypoint process in the container. type: string title: ImageConfig defines the execution parameters which should be used as a base when running a container using an image. type: object x-go-package: github.com/opencontainers/image-spec/specs-go/v1 ImageData: properties: Annotations: additionalProperties: type: string type: object Architecture: type: string Author: type: string Comment: type: string Config: $ref: '#/definitions/ImageConfig' Created: format: date-time type: string Digest: $ref: '#/definitions/Digest' GraphDriver: $ref: '#/definitions/DriverData' Healthcheck: $ref: '#/definitions/Schema2HealthConfig' History: items: $ref: '#/definitions/History' type: array Id: type: string x-go-name: ID Labels: additionalProperties: type: string type: object ManifestType: type: string NamesHistory: items: type: string type: array Os: type: string Parent: type: string RepoDigests: items: type: string type: array RepoTags: items: type: string type: array RootFS: $ref: '#/definitions/RootFS' Size: format: int64 type: integer User: type: string Version: type: string VirtualSize: format: int64 type: integer title: ImageData holds the inspect information of an image. type: object x-go-package: go.podman.io/podman/v6/pkg/inspect Duration: description: 'A Duration represents the elapsed time between two instants as an int64 nanosecond count. The representation limits the largest representable duration to approximately 290 years.' format: int64 type: integer x-go-package: time RootFS: properties: Layers: items: $ref: '#/definitions/Digest' type: string type: array Type: type: string title: RootFS holds the root fs information of an image. type: object x-go-package: go.podman.io/podman/v6/pkg/inspect LibpodImagesPullReport: allOf: - $ref: '#/definitions/ImagePullReport' x-go-package: go.podman.io/podman/v6/pkg/api/handlers responses: errorFromRegistry: description: Error from registry schema: $ref: '#/definitions/ErrorModel' fileNotFound: description: No such file schema: $ref: '#/definitions/ErrorModel' badParamError: description: Bad parameter in request schema: $ref: '#/definitions/ErrorModel' imagesPruneLibpod: description: Image Prune schema: items: $ref: '#/definitions/PruneReport' type: array imageNotFound: description: No such image schema: $ref: '#/definitions/ErrorModel' inspectImageResponseLibpod: description: Inspect Image schema: $ref: '#/definitions/ImageData' imagesPullResponseLibpod: description: Image Pull. Errors may be detected later even if this returns HTTP status 200, and in that case, the error description will be in the `error` field. schema: $ref: '#/definitions/LibpodImagesPullReport' internalError: description: Internal server error schema: $ref: '#/definitions/ErrorModel' registrySearchResponse: description: Registry Search schema: properties: Automated: description: Automated indicates if the image was created by an automated build. type: string Description: description: Description of the image. type: string Index: description: Index is the image index example: quay.io type: string Name: description: Name is the canonical name of the image example: docker.io/library/alpine" type: string Official: description: Official indicates if it's an official image. type: string Stars: description: Stars is the number of stars of the image. format: int64 type: integer Tag: description: Tag is the image tag type: string type: object imagesRemoveResponseLibpod: description: Image Remove schema: $ref: '#/definitions/LibpodImagesRemoveReport' imageListLibpod: description: Image summary for libpod API schema: items: $ref: '#/definitions/ImageSummary' type: array imagesLoadResponseLibpod: description: Image Load schema: $ref: '#/definitions/ImageLoadReport' containerNotFound: description: No such container schema: $ref: '#/definitions/ErrorModel' imagesImportResponseLibpod: description: Image Import schema: $ref: '#/definitions/ImageImportReport' treeResponse: description: Image Tree schema: $ref: '#/definitions/ImageTreeReport' history: description: Image History schema: $ref: '#/definitions/HistoryResponse' imagesScpResponseLibpod: description: Image Scp schema: $ref: '#/definitions/ScpReport' conflictError: description: Conflict error in operation schema: $ref: '#/definitions/ErrorModel'