Podman containers (compat) API
Actions related to containers for the compatibility endpoints
Actions related to containers 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 containers (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 containers for the compatibility endpoints
name: containers (compat)
paths:
/commit:
post:
description: Create a new image from a container
operationId: ImageCommit
parameters:
- description: the name or ID of a container
in: query
name: container
type: string
- description: the repository name for the created image
in: query
name: repo
type: string
- description: tag name for the created image
in: query
name: tag
type: string
- description: commit message
in: query
name: comment
type: string
- description: author of the image
in: query
name: author
type: string
- description: pause the container before committing it
in: query
name: pause
type: boolean
- description: instructions to apply while committing in Dockerfile format
in: query
name: changes
type: string
- description: squash newly built layers into a single new layer
in: query
name: squash
type: boolean
produces:
- application/json
responses:
'201':
description: no error
'404':
$ref: '#/responses/imageNotFound'
'500':
$ref: '#/responses/internalError'
summary: New Image
tags:
- containers (compat)
/containers/{name}:
delete:
operationId: ContainerDelete
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- default: false
description: If the container is running, kill it before removing it.
in: query
name: force
type: boolean
- default: false
description: Remove the volumes associated with the container.
in: query
name: v
type: boolean
- description: not supported
in: query
name: link
type: boolean
- default: false
description: Ignore if a specified container does not exist.
in: query
name: ignore
type: boolean
- default: false
description: Remove container dependencies.
in: query
name: depend
type: boolean
- description: Number of seconds to wait before forcibly stopping the container.
in: query
name: timeout
type: integer
- default: false
description: Remove anonymous volumes associated with the container.
in: query
name: volumes
type: boolean
produces:
- application/json
responses:
'204':
description: no error
'400':
$ref: '#/responses/badParamError'
'404':
$ref: '#/responses/containerNotFound'
'409':
$ref: '#/responses/conflictError'
'500':
$ref: '#/responses/internalError'
summary: Remove a container
tags:
- containers (compat)
/containers/{name}/archive:
get:
description: Get a tar archive of files from a container
operationId: ContainerArchive
parameters:
- description: container name or id
in: path
name: name
required: true
type: string
- description: Path to a directory in the container to extract
in: query
name: path
required: true
type: string
produces:
- application/json
responses:
'200':
description: no error
schema:
format: binary
type: string
'400':
$ref: '#/responses/badParamError'
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Get files from a container
tags:
- containers (compat)
put:
description: Put a tar archive of files into a container
operationId: PutContainerArchive
parameters:
- description: container name or id
in: path
name: name
required: true
type: string
- description: Path to a directory in the container to extract
in: query
name: path
required: true
type: string
- description: if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa (1 or true)
in: query
name: noOverwriteDirNonDir
type: string
- description: copy UID/GID maps to the dest file or di (1 or true)
in: query
name: copyUIDGID
type: string
- description: tarfile of files to copy into the container
in: body
name: request
schema:
type: string
produces:
- application/json
responses:
'200':
description: no error
'400':
$ref: '#/responses/badParamError'
'403':
description: the container rootfs is read-only
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Put files into a container
tags:
- containers (compat)
/containers/{name}/attach:
post:
description: 'Attach to a container to read its output or send it input. You can attach
to the same container multiple times and you can reattach to containers
that have been detached.
It uses the same stream format as docker, see the libpod attach endpoint for a description of the format.
'
operationId: ContainerAttach
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- description: keys to use for detaching from the container
in: query
name: detachKeys
type: string
- description: Stream all logs from the container across the connection. Happens before streaming attach (if requested). At least one of logs or stream must be set
in: query
name: logs
type: boolean
- default: true
description: Attach to the container. If unset, and logs is set, only the container's logs will be sent. At least one of stream or logs must be set
in: query
name: stream
type: boolean
- description: Attach to container STDOUT
in: query
name: stdout
type: boolean
- description: Attach to container STDERR
in: query
name: stderr
type: boolean
- description: Attach to container STDIN
in: query
name: stdin
type: boolean
produces:
- application/json
responses:
'101':
description: No error, connection has been hijacked for transporting streams.
'400':
$ref: '#/responses/badParamError'
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Attach to a container
tags:
- containers (compat)
/containers/{name}/changes:
get:
description: 'Returns which files in a container''s filesystem have been added, deleted, or modified. The Kind of modification can be one of:
0: Modified
1: Added
2: Deleted
'
operationId: ContainerChanges
parameters:
- description: the name or id of the container
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 container's filesystem; adds, deletes or modifications.
tags:
- containers (compat)
/containers/{name}/export:
get:
description: Export the contents of a container as a tarball.
operationId: ContainerExport
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'200':
description: tarball is returned in body
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Export a container
tags:
- containers (compat)
/containers/{name}/json:
get:
description: Return low-level information about a container.
operationId: ContainerInspect
parameters:
- description: the name or id of the container
in: path
name: name
required: true
type: string
- default: false
description: include the size of the container
in: query
name: size
type: boolean
produces:
- application/json
responses:
'200':
$ref: '#/responses/containerInspectResponse'
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Inspect container
tags:
- containers (compat)
/containers/{name}/kill:
post:
description: Signal to send to the container as an integer or string (e.g. SIGINT)
operationId: ContainerKill
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- default: false
description: Send kill signal to all containers
in: query
name: all
type: boolean
- default: SIGKILL
description: signal to be sent to container
in: query
name: signal
type: string
produces:
- application/json
responses:
'204':
description: no error
'404':
$ref: '#/responses/containerNotFound'
'409':
$ref: '#/responses/conflictError'
'500':
$ref: '#/responses/internalError'
summary: Kill container
tags:
- containers (compat)
/containers/{name}/logs:
get:
description: Get stdout and stderr logs from a container.
operationId: ContainerLogs
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- description: Keep connection after returning logs.
in: query
name: follow
type: boolean
- description: Return logs from stdout
in: query
name: stdout
type: boolean
- description: Return logs from stderr
in: query
name: stderr
type: boolean
- description: Only return logs since this time, as a UNIX timestamp
in: query
name: since
type: string
- description: Only return logs before this time, as a UNIX timestamp
in: query
name: until
type: string
- default: false
description: Add timestamps to every log line
in: query
name: timestamps
type: boolean
- default: all
description: Only return this number of log lines from the end of the logs
in: query
name: tail
type: string
produces:
- application/json
responses:
'200':
description: logs returned as a stream in response body.
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Get container logs
tags:
- containers (compat)
/containers/{name}/pause:
post:
description: Use the cgroups freezer to suspend all processes in a container.
operationId: ContainerPause
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'204':
description: no error
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Pause container
tags:
- containers (compat)
/containers/{name}/rename:
post:
description: Change the name of an existing container.
operationId: ContainerRename
parameters:
- description: Full or partial ID or full name of the container to rename
in: path
name: name
required: true
type: string
- description: New name for the container
in: query
name: name
required: true
type: string
produces:
- application/json
responses:
'204':
description: no error
'404':
$ref: '#/responses/containerNotFound'
'409':
$ref: '#/responses/conflictError'
'500':
$ref: '#/responses/internalError'
summary: Rename an existing container
tags:
- containers (compat)
/containers/{name}/resize:
post:
description: Resize the terminal attached to a container (for use with Attach).
operationId: ContainerResize
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- description: Height to set for the terminal, in characters
in: query
name: h
type: integer
- description: Width to set for the terminal, in characters
in: query
name: w
type: integer
- description: Ignore containers not running errors
in: query
name: running
type: boolean
produces:
- application/json
responses:
'200':
$ref: '#/responses/ok'
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Resize a container's TTY
tags:
- containers (compat)
/containers/{name}/restart:
post:
operationId: ContainerRestart
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- description: timeout before sending kill signal to container
in: query
name: t
type: integer
produces:
- application/json
responses:
'204':
description: no error
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Restart container
tags:
- containers (compat)
/containers/{name}/start:
post:
operationId: ContainerStart
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- default: ctrl-p,ctrl-q
description: 'Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.'
in: query
name: detachKeys
type: string
produces:
- application/json
responses:
'204':
description: no error
'304':
$ref: '#/responses/containerAlreadyStartedError'
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Start a container
tags:
- containers (compat)
/containers/{name}/stats:
get:
description: This returns a live stream of a container’s resource usage statistics.
operationId: ContainerStats
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- default: true
description: Stream the output
in: query
name: stream
type: boolean
- default: false
description: Provide a one-shot response in which preCPU stats are blank, resulting in a single cycle return.
in: query
name: one-shot
type: boolean
produces:
- application/json
responses:
'200':
description: no error
schema:
type: object
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Get stats for a container
tags:
- containers (compat)
/containers/{name}/stop:
post:
description: Stop a container
operationId: ContainerStop
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- description: number of seconds to wait before killing container
in: query
name: t
type: integer
- description: Number of seconds to wait before killing the container (libpod alias for `t`).
in: query
name: timeout
type: integer
- default: false
description: Do not return an error if the container is already stopped.
in: query
name: ignore
type: boolean
produces:
- application/json
responses:
'204':
description: no error
'304':
$ref: '#/responses/containerAlreadyStoppedError'
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Stop a container
tags:
- containers (compat)
/containers/{name}/top:
get:
operationId: ContainerTop
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- default: -ef
description: arguments to pass to ps such as aux.
in: query
name: ps_args
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/containerTopResponse'
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: List processes running inside a container
tags:
- containers (compat)
/containers/{name}/unpause:
post:
description: Resume a paused container
operationId: ContainerUnpause
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'204':
description: no error
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Unpause container
tags:
- containers (compat)
/containers/{name}/update:
post:
description: Change configuration settings for an existing container without requiring recreation.
operationId: ContainerUpdate
parameters:
- description: Full or partial ID or full name of the container to rename
in: path
name: name
required: true
type: string
- description: attributes for updating the container
in: body
name: resources
schema:
$ref: '#/definitions/containerUpdateRequest'
produces:
- application/json
responses:
'200':
description: no error
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Update configuration of an existing container, allowing changes to resource limits
tags:
- containers (compat)
/containers/{name}/wait:
post:
description: 'Block until a container stops or given condition is met.
This is a Docker-compatible endpoint.
'
operationId: ContainerWait
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- default: not-running
description: "Wait condition. Valid values are:\n - not-running (default) - return when the container is not running\n (stopped, exited, or was never started).\n - next-exit - wait for the next time the container stops.\n If the container is running, block until it exits.\n If the container is already stopped, block until\n the next start-and-exit cycle.\n - removed - wait until the container is removed.\n"
in: query
name: condition
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/containerWaitResponse'
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Wait on a container
tags:
- containers (compat)
/containers/create:
post:
operationId: ContainerCreate
parameters:
- description: container name
in: query
name: name
type: string
- description: Container to create
in: body
name: body
required: true
schema:
$ref: '#/definitions/CreateContainerConfig'
produces:
- application/json
responses:
'201':
$ref: '#/responses/containerCreateResponse'
'400':
$ref: '#/responses/badParamError'
'404':
$ref: '#/responses/containerNotFound'
'409':
$ref: '#/responses/conflictError'
'500':
$ref: '#/responses/internalError'
summary: Create a container
tags:
- containers (compat)
/containers/json:
get:
description: Returns a list of containers
operationId: ContainerList
parameters:
- default: false
description: Return all containers. By default, only running containers are shown
in: query
name: all
type: boolean
- default: false
description: Return containers in storage not controlled by Podman
in: query
name: external
type: boolean
- description: Return this number of most recently created containers, including non-running ones.
in: query
name: limit
type: integer
- default: false
description: Return the size of container as fields SizeRw and SizeRootFs.
in: query
name: size
type: boolean
- description: 'A JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters:
- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)
- `before`=(`<container id>` or `<container name>`)
- `expose`=(`<port>[/<proto>]` or `<startport-endport>/[<proto>]`)
- `exited=<int>` containers with exit code of `<int>`
- `health`=(`starting`, `healthy`, `unhealthy` or `none`)
- `id=<ID>` a container''s ID
- `is-task`=(`true` or `false`)
- `label`=(`key` or `"key=value"`) of a container label
- `name=<name>` a container''s name
- `network`=(`<network id>` or `<network name>`)
- `publish`=(`<port>[/<proto>]` or `<startport-endport>/[<proto>]`)
- `since`=(`<container id>` or `<container name>`)
- `status`=(`created`, `restarting`, `running`, `removing`, `paused`, `exited` or `dead`)
- `volume`=(`<volume name>` or `<mount point destination>`)
'
in: query
name: filters
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/containersList'
'400':
$ref: '#/responses/badParamError'
'500':
$ref: '#/responses/internalError'
summary: List containers
tags:
- containers (compat)
/containers/prune:
post:
description: Remove containers not in use
operationId: ContainerPrune
parameters:
- description: "Filters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:\n - `until=<timestamp>` Prune containers 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 containers 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/containersPrune'
'500':
$ref: '#/responses/internalError'
summary: Delete stopped containers
tags:
- containers (compat)
/libpod/containers/{name}/archive:
get:
description: Copy a tar archive of files from a container
operationId: ContainerArchiveLibpod
parameters:
- description: container name or id
in: path
name: name
required: true
type: string
- description: Path to a directory in the container to extract
in: query
name: path
required: true
type: string
- description: JSON encoded map[string]string to translate paths
in: query
name: rename
type: string
produces:
- application/json
responses:
'200':
description: no error
schema:
format: binary
type: string
'400':
$ref: '#/responses/badParamError'
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Copy files from a container
tags:
- containers (compat)
definitions:
HealthConfig:
title: HealthConfig holds configuration settings for the HEALTHCHECK feature.
type: object
x-go-package: github.com/moby/moby/api/types/container
TmpfsOptions:
properties:
Mode:
$ref: '#/definitions/FileMode'
Options:
description: 'Options to be passed to the tmpfs mount. An array of arrays. Flag
options should be provided as 1-length arrays. Other types should be
provided as 2-length arrays, where the first item is the key and the
second the value.'
items:
items:
type: string
type: array
type: array
SizeBytes:
description: 'Size sets the size of the tmpfs, in bytes.
This will be converted to an operating system specific value
depending on the host. For example, on linux, it will be converted to
use a ''k'', ''m'' or ''g'' syntax. BSD, though not widely supported with
docker, uses a straight byte value.
Percentages are not supported.'
format: int64
type: integer
title: TmpfsOptions defines options specific to mounts of type "tmpfs".
type: object
x-go-package: github.com/moby/moby/api/types/mount
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
InspectResponse:
description: endpoint.
properties:
AppArmorProfile:
type: string
Args:
items:
type: string
type: array
Config:
$ref: '#/definitions/Config'
Created:
type: string
Driver:
type: string
ExecIDs:
items:
type: string
type: array
GraphDriver:
$ref: '#/definitions/DriverData'
HostConfig:
$ref: '#/definitions/HostConfig'
HostnamePath:
type: string
HostsPath:
type: string
Id:
type: string
x-go-name: ID
Image:
type: string
ImageManifestDescriptor:
$ref: '#/definitions/Descriptor'
LogPath:
type: string
MountLabel:
type: string
Mounts:
items:
$ref: '#/definitions/MountPoint'
type: array
Name:
type: string
NetworkSettings:
$ref: '#/definitions/NetworkSettings'
Path:
type: string
Platform:
type: string
ProcessLabel:
type: string
ResolvConfPath:
type: string
RestartCount:
format: int64
type: integer
SizeRootFs:
format: int64
type: integer
SizeRw:
format: int64
type: integer
State:
$ref: '#/definitions/State'
Storage:
$ref: '#/definitions/Storage'
title: InspectResponse is the response for the GET "/containers/{name:.*}/json"
type: object
x-go-pa
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/podman/refs/heads/main/openapi/podman-containers-compat-api-openapi.yml