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 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
name: containers
paths:
/libpod/commit:
post:
description: Create a new image from a container
operationId: ImageCommitLibpod
parameters:
- description: the name or ID of a container
in: query
name: container
required: true
type: string
- description: author of the image
in: query
name: author
type: string
- description: instructions to apply while committing in Dockerfile format (i.e. "CMD=/bin/foo")
in: query
items:
type: string
name: changes
type: array
- description: commit message
in: query
name: comment
type: string
- description: format of the image manifest and metadata (default "oci")
in: query
name: format
type: string
- description: pause the container before committing it
in: query
name: pause
type: boolean
- description: squash the container before committing it
in: query
name: squash
type: boolean
- description: the repository name for the created image
in: query
name: repo
type: string
- description: output from commit process
in: query
name: stream
type: boolean
- description: tag name for the created image
in: query
name: tag
type: string
produces:
- application/json
responses:
'201':
description: no error
'404':
$ref: '#/responses/imageNotFound'
'500':
$ref: '#/responses/internalError'
summary: Commit
tags:
- containers
/libpod/containers/{name}:
delete:
description: Delete container
operationId: ContainerDeleteLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- description: additionally remove containers that depend on the container to be removed
in: query
name: depend
type: boolean
- description: force stop container if running
in: query
name: force
type: boolean
- description: ignore errors when the container to be removed does not existxo
in: query
name: ignore
type: boolean
- default: 10
description: number of seconds to wait before killing container when force removing
in: query
name: timeout
type: integer
- description: delete volumes
in: query
name: v
type: boolean
produces:
- application/json
responses:
'200':
$ref: '#/responses/containerRemoveLibpod'
'204':
description: no error
'400':
$ref: '#/responses/badParamError'
'404':
$ref: '#/responses/containerNotFound'
'409':
$ref: '#/responses/conflictError'
'500':
$ref: '#/responses/internalError'
summary: Delete container
tags:
- containers
/libpod/containers/{name}/archive:
put:
description: Copy a tar archive of files into a container
operationId: PutContainerArchiveLibpod
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
- default: true
description: pause the container while copying (defaults to true)
in: query
name: pause
type: boolean
- 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: Copy files into a container
tags:
- containers
/libpod/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.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`,
and `stderr` on the same socket.
This is the response from the service for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
After the headers and two new lines, the TCP connection can now be used
for raw, bidirectional communication between the client and server.
To inform potential proxies about connection hijacking, the client
can also optionally send connection upgrade headers.
For example, the client sends this request to upgrade the connection:
```
POST /v4.6.0/libpod/containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```
The service will respond with a `101 UPGRADED` response, and will
similarly follow with the raw stream:
```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp
[STREAM]
```
### Stream format
When the TTY setting is disabled for the container,
the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream
(starting with v4.7.0, previously application/vnd.docker.raw-stream was always used)
and the stream over the hijacked connected is multiplexed to separate out
`stdout` and `stderr`. The stream consists of a series of frames, each
containing a header and a payload.
The header contains the information about the output stream type and the size of
the payload.
It is encoded on the first eight bytes like this:
```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```
`STREAM_TYPE` can be:
- 0: `stdin` (is written on `stdout`)
- 1: `stdout`
- 2: `stderr`
`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size
encoded as big endian.
Following the header is the payload, which contains the specified number of
bytes as written in the size.
The simplest way to implement this protocol is the following:
1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.
### Stream format when using a TTY
When the TTY setting is enabled for the container,
the stream is not multiplexed. The data exchanged over the hijacked
connection is simply the raw data from the process PTY and client''s
`stdin`.
'
operationId: ContainerAttachLibpod
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
/libpod/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: ContainerChangesLibpod
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
/libpod/containers/{name}/checkpoint:
post:
operationId: ContainerCheckpointLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- description: keep all temporary checkpoint files
in: query
name: keep
type: boolean
- description: leave the container running after writing checkpoint to disk
in: query
name: leaveRunning
type: boolean
- description: checkpoint a container with established TCP connections
in: query
name: tcpEstablished
type: boolean
- description: export the checkpoint image to a tar.gz
in: query
name: export
type: boolean
- description: do not include root file-system changes when exporting. can only be used with export
in: query
name: ignoreRootFS
type: boolean
- description: do not include associated volumes. can only be used with export
in: query
name: ignoreVolumes
type: boolean
- description: dump the container's memory information only, leaving the container running. only works on runc 1.0-rc or higher
in: query
name: preCheckpoint
type: boolean
- description: check out the container with previous criu image files in pre-dump. only works on runc 1.0-rc or higher
in: query
name: withPrevious
type: boolean
- description: checkpoint a container with filelocks
in: query
name: fileLocks
type: boolean
- description: add checkpoint statistics to the returned CheckpointReport
in: query
name: printStats
type: boolean
produces:
- application/json
responses:
'200':
description: tarball is returned in body if exported
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Checkpoint a container
tags:
- containers
/libpod/containers/{name}/exists:
get:
description: Quick way to determine if a container exists by name or ID
operationId: ContainerExistsLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'204':
description: container exists
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Check if container exists
tags:
- containers
/libpod/containers/{name}/export:
get:
description: Export the contents of a container as a tarball.
operationId: ContainerExportLibpod
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
/libpod/containers/{name}/healthcheck:
get:
description: Execute the defined healthcheck and return information about the results
operationId: ContainerHealthcheckLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/healthCheck'
'404':
$ref: '#/responses/containerNotFound'
'409':
description: container has no healthcheck or is not running
'500':
$ref: '#/responses/internalError'
summary: Run a container's healthcheck
tags:
- containers
/libpod/containers/{name}/init:
post:
description: Performs all tasks necessary for initializing the container but does not start the container.
operationId: ContainerInitLibpod
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
'304':
description: container already initialized
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Initialize a container
tags:
- containers
/libpod/containers/{name}/json:
get:
description: Return low-level information about a container.
operationId: ContainerInspectLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- description: display filesystem usage
in: query
name: size
type: boolean
produces:
- application/json
responses:
'200':
$ref: '#/responses/containerInspectResponseLibpod'
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Inspect container
tags:
- containers
/libpod/containers/{name}/kill:
post:
description: send a signal to a container, defaults to killing the container
operationId: ContainerKillLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- default: SIGKILL
description: signal to be sent to container, either by integer or SIG_ name
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
/libpod/containers/{name}/logs:
get:
description: 'Get stdout and stderr logs from a container.
The stream format is the same as described in the attach endpoint.
'
operationId: ContainerLogsLibpod
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
/libpod/containers/{name}/mount:
post:
description: Mount a container to the filesystem
operationId: ContainerMountLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- default: false
description: Include external containers that are not managed by Podman.
in: query
name: external
type: boolean
produces:
- application/json
responses:
'200':
description: mounted container
schema:
description: id
example: /var/lib/containers/storage/overlay/f3f693bd88872a1e3193f4ebb925f4c282e8e73aadb8ab3e7492754dda3a02a4/merged
type: string
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Mount a container
tags:
- containers
/libpod/containers/{name}/pause:
post:
description: Use the cgroups freezer to suspend all processes in a container.
operationId: ContainerPauseLibpod
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 a container
tags:
- containers
/libpod/containers/{name}/rename:
post:
description: Change the name of an existing container.
operationId: ContainerRenameLibpod
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
/libpod/containers/{name}/resize:
post:
description: Resize the terminal attached to a container (for use with Attach).
operationId: ContainerResizeLibpod
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'
'409':
$ref: '#/responses/conflictError'
'500':
$ref: '#/responses/internalError'
summary: Resize a container's TTY
tags:
- containers
/libpod/containers/{name}/restart:
post:
operationId: ContainerRestartLibpod
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 (Docker compatibility)
in: query
name: t
type: integer
- description: number of seconds to wait before killing container
in: query
name: timeout
type: integer
produces:
- application/json
responses:
'204':
description: no error
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Restart a container
tags:
- containers
/libpod/containers/{name}/restore:
post:
description: Restore a container from a checkpoint.
operationId: ContainerRestoreLibpod
parameters:
- description: the name or id of the container
in: path
name: name
required: true
type: string
- description: the name of the container when restored from a tar. can only be used with import
in: query
name: name
type: string
- description: keep all temporary checkpoint files
in: query
name: keep
type: boolean
- description: restore a container with established TCP connections
in: query
name: tcpEstablished
type: boolean
- description: restore a container but close the TCP connections
in: query
name: tcpClose
type: boolean
- description: import the restore from a checkpoint tar.gz
in: query
name: import
type: boolean
- description: do not include root file-system changes when exporting. can only be used with import
in: query
name: ignoreRootFS
type: boolean
- description: do not restore associated volumes. can only be used with import
in: query
name: ignoreVolumes
type: boolean
- description: ignore IP address if set statically
in: query
name: ignoreStaticIP
type: boolean
- description: ignore MAC address if set statically
in: query
name: ignoreStaticMAC
type: boolean
- description: restore a container with file locks
in: query
name: fileLocks
type: boolean
- description: add restore statistics to the returned RestoreReport
in: query
name: printStats
type: boolean
- description: pod to restore into
in: query
name: pod
type: string
produces:
- application/json
responses:
'200':
description: tarball is returned in body if exported
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Restore a container
tags:
- containers
/libpod/containers/{name}/start:
post:
operationId: ContainerStartLibpod
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
/libpod/containers/{name}/stats:
get:
description: DEPRECATED. This endpoint will be removed with the next major release. Please use /libpod/containers/stats instead.
operationId: ContainerStatsLibpod
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
produces:
- application/json
responses:
'200':
description: no error
'404':
$ref: '#/responses/containerNotFound'
'409':
$ref: '#/responses/conflictError'
'500':
$ref: '#/responses/internalError'
summary: Get stats for a container
tags:
- containers
/libpod/containers/{name}/stop:
post:
operationId: ContainerStopLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
- default: 10
description: number of seconds to wait before killing container
in: query
name: timeout
type: integer
- default: false
description: do not return error if 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
/libpod/containers/{name}/top:
get:
description: List processes running inside a container
operationId: ContainerTopLibpod
parameters:
- description: Name of container to query for processes (As of version 1.xx)
in: path
name: name
required: true
type: string
- description: when true, repeatedly stream the latest output (As of version 4.0)
in: query
name: stream
type: boolean
- default: 5
description: if streaming, delay in seconds between updates. Must be >1. (As of version 4.0)
in: query
name: delay
type: integer
- description: 'arguments to pass to ps such as aux.
'
in: query
items:
type: string
name: ps_args
type: array
produces:
- application/json
responses:
'200':
$ref: '#/responses/containerTopResponse'
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: List processes
tags:
- containers
/libpod/containers/{name}/unmount:
post:
description: Unmount a container from the filesystem
operationId: ContainerUnmountLibpod
parameters:
- description: the name or ID of the container
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'204':
description: ok
'404':
$ref: '#/responses/containerNotFound'
'500':
$ref: '#/responses/internalError'
summary: Unmount a container
tags:
- containers
/libpod/containers/{name}/unpause:
post:
operationId: ContainerUnpauseLibpod
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
/libpod/containers/{name}/update:
post:
description: Updates the configuration of an existing container, allowing changes to resource limits and healthchecks.
operationId: ContainerUpdateLibpod
parameters:
- description: Full or partial ID or full name of the container to update
in: path
name: name
required: true
type: string
- description: New restart policy for the container.
in: query
name: restartPolicy
type: string
- description: New amount of retries for the container's restart policy. Only allowed if restartPolicy is set to on-failure
in: query
name: restartRetries
type: integer
- description: attributes for updating the container
in: body
name: config
schema:
$ref: '#/definitions/UpdateEntities'
pro
# --- truncated at 32 KB (176 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/podman/refs/heads/main/openapi/podman-containers-api-openapi.yml