The Podman REST API (libpod) provides a Docker-compatible API surface plus Podman-specific Libpod endpoints for managing containers, images, pods, volumes, networks, secrets, manifests, and the Podman system service. The API is published as a Swagger 2.0 specification generated from the Podman source tree.
basePath: /
consumes:
- application/json
- application/x-tar
definitions:
AccessMode:
properties:
BlockVolume:
$ref: '#/definitions/TypeBlock'
MountVolume:
$ref: '#/definitions/TypeMount'
Scope:
$ref: '#/definitions/Scope'
Sharing:
$ref: '#/definitions/SharingMode'
title: AccessMode defines the access mode of a volume.
type: object
x-go-package: github.com/moby/moby/api/types/volume
Address:
properties:
Addr:
type: string
PrefixLength:
format: int64
type: integer
title: Address represents an IP address.
type: object
x-go-package: go.podman.io/podman/v6/libpod/define
ArtifactAddReport:
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities
ArtifactInspectReport:
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities
ArtifactListReport:
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities
ArtifactPullReport:
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities
ArtifactPushReport:
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities
ArtifactRemoveReport:
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities
ArtifactVolume:
description: |-
ArtifactVolume is a volume based on a artifact. The artifact blobs will
be bind mounted directly as files and must always be read only.
properties:
destination:
description: |-
Destination is the absolute path of the mount in the container.
If path is a file in the container, then the artifact must consist of a single blob.
Otherwise if it is a directory or does not exists all artifact blobs will be mounted
into this path as files. As name the "org.opencontainers.image.title" will be used if
available otherwise the digest is used as name.
type: string
x-go-name: Destination
digest:
description: |-
Digest can be used to filter a single blob from a multi blob artifact by the given digest.
When this option is set the file name in the container defaults to the digest even when
the title annotation exist.
Optional. Conflicts with Title.
type: string
x-go-name: Digest
name:
description: |-
Name is the name that should be used for the path inside the container. When a single blob
is mounted the name is used as is. If multiple blobs are mounted then mount them as
"<name>-x" where x is a 0 indexed integer based on the layer order.
Optional.
type: string
x-go-name: Name
source:
description: Source is the name or digest of the artifact that should be mounted
type: string
x-go-name: Source
title:
description: |-
Title can be used for multi blob artifacts to only mount the one specific blob that
matches the "org.opencontainers.image.title" annotation.
Optional. Conflicts with Digest.
type: string
x-go-name: Title
type: object
x-go-package: go.podman.io/podman/v6/pkg/specgen
AttestationProperties:
properties:
For:
$ref: '#/definitions/Digest'
type: object
x-go-package: github.com/moby/moby/api/types/image
AuthConfig:
description: AuthConfig contains authorization information for connecting to a Registry
properties:
auth:
type: string
x-go-name: Auth
email:
description: |-
Email is an optional value associated with the username.
This field is deprecated and will be removed in a later
version of docker.
type: string
x-go-name: Email
identitytoken:
description: |-
IdentityToken is used to authenticate the user and get
an access token for the registry.
type: string
x-go-name: IdentityToken
password:
type: string
x-go-name: Password
registrytoken:
description: RegistryToken is a bearer token to be sent to a registry
type: string
x-go-name: RegistryToken
serveraddress:
type: string
x-go-name: ServerAddress
username:
type: string
x-go-name: Username
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities/types
AuthReport:
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities
AutoUserNsOptions:
properties:
AdditionalGIDMappings:
description: |-
AdditionalGIDMappings specified additional GID mappings to include in
the generated user namespace.
items:
$ref: '#/definitions/IDMap'
type: array
AdditionalUIDMappings:
description: |-
AdditionalUIDMappings specified additional UID mappings to include in
the generated user namespace.
items:
$ref: '#/definitions/IDMap'
type: array
GroupFile:
description: GroupFile to use if the container uses a volume.
type: string
InitialSize:
description: |-
InitialSize defines the minimum size for the user namespace.
The created user namespace will have at least this size.
format: uint32
type: integer
PasswdFile:
description: PasswdFile to use if the container uses a volume.
type: string
Size:
description: |-
Size defines the size for the user namespace. If it is set to a
value bigger than 0, the user namespace will have exactly this size.
If it is not set, some heuristics will be used to find its size.
format: uint32
type: integer
title: AutoUserNsOptions defines how to automatically create a user namespace.
type: object
x-go-package: go.podman.io/storage/types
Availability:
title: Availability specifies the availability of the volume.
type: string
x-go-package: github.com/moby/moby/api/types/volume
BindOptions:
properties:
CreateMountpoint:
type: boolean
NonRecursive:
type: boolean
Propagation:
$ref: '#/definitions/Propagation'
ReadOnlyForceRecursive:
description: ReadOnlyForceRecursive raises an error if the mount cannot be made recursively read-only.
type: boolean
ReadOnlyNonRecursive:
description: |-
ReadOnlyNonRecursive makes the mount non-recursively read-only, but still leaves the mount recursive
(unless NonRecursive is set to true in conjunction).
type: boolean
title: BindOptions defines options specific to mounts of type "bind".
type: object
x-go-package: github.com/moby/moby/api/types/mount
BuildIdentity:
properties:
CreatedAt:
description: CreatedAt is the time when the build ran.
format: date-time
type: string
Ref:
description: |-
Ref is the identifier for the build request. This reference can be used to
look up the build details in BuildKit history API.
type: string
title: BuildIdentity contains build reference information if image was created via build.
type: object
x-go-package: github.com/moby/moby/api/types/image
CPUUsage:
properties:
idlePercent:
format: double
type: number
x-go-name: IdlePercent
systemPercent:
format: double
type: number
x-go-name: SystemPercent
userPercent:
format: double
type: number
x-go-name: UserPercent
type: object
x-go-package: go.podman.io/podman/v6/libpod/define
CapacityRange:
description: |-
CapacityRange describes the minimum and maximum capacity a volume should be
created with
properties:
LimitBytes:
description: |-
LimitBytes specifies that a volume must not be bigger than this. The
value of 0 indicates an unspecified maximum
format: int64
type: integer
RequiredBytes:
description: |-
RequiredBytes specifies that a volume must be at least this big. The
value of 0 indicates an unspecified minimum.
format: int64
type: integer
type: object
x-go-package: github.com/moby/moby/api/types/volume
CgroupSpec:
title: CgroupSpec represents the cgroup to use for the container.
type: string
x-go-package: github.com/moby/moby/api/types/container
CgroupnsMode:
description: CgroupnsMode represents the cgroup namespace mode of the container
type: string
x-go-package: github.com/moby/moby/api/types/container
ClusterOptions:
title: ClusterOptions specifies options for a Cluster volume.
type: object
x-go-package: github.com/moby/moby/api/types/mount
ClusterVolume:
description: |-
ClusterVolume contains options and information specific to, and only present
on, Swarm CSI cluster volumes.
properties:
CreatedAt:
format: date-time
type: string
ID:
description: |-
ID is the Swarm ID of the volume. Because cluster volumes are Swarm
objects, they have an ID, unlike non-cluster volumes, which only have a
Name. This ID can be used to refer to the cluster volume.
type: string
Info:
$ref: '#/definitions/Info'
PublishStatus:
description: |-
PublishStatus contains the status of the volume as it pertains to its
publishing on Nodes.
items:
$ref: '#/definitions/PublishStatus'
type: array
Spec:
$ref: '#/definitions/ClusterVolumeSpec'
UpdatedAt:
format: date-time
type: string
Version:
$ref: '#/definitions/Version'
type: object
x-go-package: github.com/moby/moby/api/types/volume
ClusterVolumeSpec:
properties:
AccessMode:
$ref: '#/definitions/AccessMode'
AccessibilityRequirements:
$ref: '#/definitions/TopologyRequirement'
Availability:
$ref: '#/definitions/Availability'
CapacityRange:
$ref: '#/definitions/CapacityRange'
Group:
description: |-
Group defines the volume group of this volume. Volumes belonging to the
same group can be referred to by group name when creating Services.
Referring to a volume by group instructs swarm to treat volumes in that
group interchangeably for the purpose of scheduling. Volumes with an
empty string for a group technically all belong to the same, emptystring
group.
type: string
Secrets:
description: |-
Secrets defines Swarm Secrets that are passed to the CSI storage plugin
when operating on this volume.
items:
$ref: '#/definitions/Secret'
type: array
title: ClusterVolumeSpec contains the spec used to create this volume.
type: object
x-go-package: github.com/moby/moby/api/types/volume
ComponentVersion:
description: ServiceOptions provides the input for starting an API and sidecar pprof services
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities
Config:
description: |-
It should hold only portable information about the container.
Here, "portable" means "independent from the host we are running on".
Non-portable information *should* appear in HostConfig.
All fields added to this struct must be marked `omitempty` to keep getting
predictable hashes from the old `v1Compatibility` configuration.
properties:
ArgsEscaped:
type: boolean
AttachStderr:
type: boolean
AttachStdin:
type: boolean
AttachStdout:
type: boolean
Cmd:
items:
type: string
type: array
Domainname:
type: string
Entrypoint:
items:
type: string
type: array
Env:
items:
type: string
type: array
ExposedPorts:
$ref: '#/definitions/PortSet'
Healthcheck:
$ref: '#/definitions/HealthConfig'
Hostname:
type: string
Image:
type: string
Labels:
additionalProperties:
type: string
type: object
NetworkDisabled:
type: boolean
OnBuild:
items:
type: string
type: array
OpenStdin:
type: boolean
Shell:
items:
type: string
type: array
StdinOnce:
type: boolean
StopSignal:
type: string
StopTimeout:
format: int64
type: integer
Tty:
type: boolean
User:
type: string
Volumes:
additionalProperties:
type: object
type: object
WorkingDir:
type: string
title: Config contains the configuration data about a container.
type: object
x-go-package: github.com/moby/moby/api/types/container
ConfigReference:
description: |-
ConfigReference The config-only network source to provide the configuration for
this network.
properties:
Network:
description: |-
The name of the config-only network that provides the network's
configuration. The specified network must be an existing config-only
network. Only network names are allowed, not network IDs.
example: config_only_network_01
type: string
type: object
x-go-package: github.com/moby/moby/api/types/network
ConmonInfo:
description: ConmonInfo describes the conmon executable being used
properties:
package:
type: string
x-go-name: Package
path:
type: string
x-go-name: Path
version:
type: string
x-go-name: Version
type: object
x-go-package: go.podman.io/podman/v6/libpod/define
ConnectRequest:
properties:
Container:
description: The ID or name of the container to connect to the network.
example: 3613f73ba0e4
type: string
EndpointConfig:
$ref: '#/definitions/EndpointSettings'
required:
- Container
title: ConnectRequest NetworkConnectRequest represents the data to be used to connect a container to a network.
type: object
x-go-package: github.com/moby/moby/api/types/network
Consistency:
title: Consistency represents the consistency requirements of a mount.
type: string
x-go-package: github.com/moby/moby/api/types/mount
Container:
properties:
Command:
type: string
Config:
$ref: '#/definitions/Config'
Created:
format: int64
type: integer
DefaultReadOnlyNonRecursive:
type: boolean
Health:
$ref: '#/definitions/HealthSummary'
HostConfig:
$ref: '#/definitions/HostConfig'
type: object
Id:
type: string
x-go-name: ID
Image:
type: string
ImageID:
type: string
ImageManifestDescriptor:
$ref: '#/definitions/Descriptor'
Labels:
additionalProperties:
type: string
type: object
Mounts:
items:
$ref: '#/definitions/MountPoint'
type: array
Name:
type: string
Names:
items:
type: string
type: array
NetworkSettings:
$ref: '#/definitions/NetworkSettingsSummary'
NetworkingConfig:
$ref: '#/definitions/NetworkingConfig'
Platform:
$ref: '#/definitions/Platform'
Ports:
items:
$ref: '#/definitions/PortSummary'
type: array
SizeRootFs:
format: int64
type: integer
SizeRw:
format: int64
type: integer
State:
$ref: '#/definitions/ContainerState'
Status:
type: string
type: object
x-go-package: go.podman.io/podman/v6/pkg/api/handlers
ContainerBasicConfig:
properties:
annotations:
additionalProperties:
type: string
description: |-
Annotations are key-value options passed into the container runtime
that can be used to trigger special behavior.
Optional.
type: object
x-go-name: Annotations
command:
description: |-
Command is the container's command.
If not given and Image is specified, this will be populated by the
image's configuration.
Optional.
items:
type: string
type: array
x-go-name: Command
conmon_pid_file:
description: |-
ConmonPidFile is a path at which a PID file for Conmon will be
placed.
If not given, a default location will be used.
Optional.
type: string
x-go-name: ConmonPidFile
containerCreateCommand:
description: |-
ContainerCreateCommand is the command that was used to create this
container.
This will be shown in the output of Inspect() on the container, and
may also be used by some tools that wish to recreate the container
(e.g. `podman generate systemd --new`).
Optional.
items:
type: string
type: array
x-go-name: ContainerCreateCommand
dependencyContainers:
description: |-
DependencyContainers is an array of containers this container
depends on. Dependency containers must be started before this
container. Dependencies can be specified by name or full/partial ID.
Optional.
items:
type: string
type: array
x-go-name: DependencyContainers
entrypoint:
description: |-
Entrypoint is the container's entrypoint.
If not given and Image is specified, this will be populated by the
image's configuration.
Optional.
items:
type: string
type: array
x-go-name: Entrypoint
env:
additionalProperties:
type: string
description: |-
Env is a set of environment variables that will be set in the
container.
Optional.
type: object
x-go-name: Env
env_host:
description: |-
EnvHost indicates that the host environment should be added to container
Optional.
type: boolean
x-go-name: EnvHost
envmerge:
description: |-
EnvMerge takes the specified environment variables from image and preprocess them before injecting them into the
container.
Optional.
items:
type: string
type: array
x-go-name: EnvMerge
group_entry:
description: |-
GroupEntry specifies an arbitrary string to append to the container's /etc/group file.
Optional.
type: string
x-go-name: GroupEntry
hostname:
description: |-
Hostname is the container's hostname. If not set, the hostname will
not be modified (if UtsNS is not private) or will be set to the
container ID (if UtsNS is private).
Conflicts with UtsNS if UtsNS is not set to private.
Optional.
type: string
x-go-name: Hostname
hostusers:
description: |-
HostUsers is a list of host usernames or UIDs to add to the container
etc/passwd file
items:
type: string
type: array
x-go-name: HostUsers
httpproxy:
description: |-
EnvHTTPProxy indicates that the http host proxy environment variables
should be added to container
Optional.
type: boolean
x-go-name: HTTPProxy
init_container_type:
description: |-
InitContainerType describes if this container is an init container
and if so, what type: always or once.
Optional.
type: string
x-go-name: InitContainerType
labels:
additionalProperties:
type: string
description: |-
Labels are key-value pairs that are used to add metadata to
containers.
Optional.
type: object
x-go-name: Labels
log_configuration:
$ref: '#/definitions/LogConfigLibpod'
manage_password:
description: Passwd is a container run option that determines if we are validating users/groups before running the container
type: boolean
x-go-name: Passwd
name:
description: |-
Name is the name the container will be given.
If no name is provided, one will be randomly generated.
Optional.
type: string
x-go-name: Name
oci_runtime:
description: |-
OCIRuntime is the name of the OCI runtime that will be used to create
the container.
If not specified, the default will be used.
Optional.
type: string
x-go-name: OCIRuntime
passwd_entry:
description: |-
PasswdEntry specifies an arbitrary string to append to the container's /etc/passwd file.
Optional.
type: string
x-go-name: PasswdEntry
personality:
$ref: '#/definitions/LinuxPersonality'
pidns:
$ref: '#/definitions/Namespace'
pod:
description: |-
Pod is the ID of the pod the container will join.
Optional.
type: string
x-go-name: Pod
remove:
description: |-
Remove indicates if the container should be removed once it has been started
and exits.
Optional.
type: boolean
x-go-name: Remove
removeImage:
description: |-
RemoveImage indicates that the container should remove the image it
was created from after it exits.
Only allowed if Remove is set to true and Image, not Rootfs, is in
use.
Optional.
type: boolean
x-go-name: RemoveImage
restart_policy:
description: |-
RestartPolicy is the container's restart policy - an action which
will be taken when the container exits.
If not given, the default policy, which does nothing, will be used.
Optional.
type: string
x-go-name: RestartPolicy
restart_tries:
description: |-
RestartRetries is the number of attempts that will be made to restart
the container.
Only available when RestartPolicy is set to "on-failure".
Optional.
format: uint64
type: integer
x-go-name: RestartRetries
sdnotifyMode:
description: |-
Determine how to handle the NOTIFY_SOCKET - do we participate or pass it through
"container" - let the OCI runtime deal with it, advertise conmon's MAINPID
"conmon-only" - advertise conmon's MAINPID, send READY when started, don't pass to OCI
"ignore" - unset NOTIFY_SOCKET
Optional.
type: string
x-go-name: SdNotifyMode
secret_env:
additionalProperties:
type: string
description: |-
EnvSecrets are secrets that will be set as environment variables
Optional.
type: object
x-go-name: EnvSecrets
stdin:
description: |-
Stdin is whether the container will keep its STDIN open.
Optional.
type: boolean
x-go-name: Stdin
stop_signal:
$ref: '#/definitions/Signal'
stop_timeout:
description: |-
StopTimeout is a timeout between the container's stop signal being
sent and SIGKILL being sent.
If not provided, the default will be used.
If 0 is used, stop signal will not be sent, and SIGKILL will be sent
instead.
Optional.
format: uint64
type: integer
x-go-name: StopTimeout
sysctl:
additionalProperties:
type: string
description: Sysctl sets kernel parameters for the container
type: object
x-go-name: Sysctl
systemd:
description: |-
Systemd is whether the container will be started in systemd mode.
Valid options are "true", "false", and "always".
"true" enables this mode only if the binary run in the container is
sbin/init or systemd. "always" unconditionally enables systemd mode.
"false" unconditionally disables systemd mode.
If enabled, mounts and stop signal will be modified.
If set to "always" or set to "true" and conditionally triggered,
conflicts with StopSignal.
If not specified, "false" will be assumed.
Optional.
type: string
x-go-name: Systemd
terminal:
description: |-
Terminal is whether the container will create a PTY.
Optional.
type: boolean
x-go-name: Terminal
timeout:
description: |-
Timeout is a maximum time in seconds the container will run before
main process is sent SIGKILL.
If 0 is used, signal will not be sent. Container can run indefinitely
if they do not stop after the default termination signal.
Optional.
format: uint64
type: integer
x-go-name: Timeout
timezone:
description: |-
Timezone is the timezone inside the container.
Local means it has the same timezone as the host machine
Optional.
type: string
x-go-name: Timezone
unsetenv:
description: |-
UnsetEnv unsets the specified default environment variables from the image or from built-in or containers.conf
Optional.
items:
type: string
type: array
x-go-name: UnsetEnv
unsetenvall:
description: |-
UnsetEnvAll unsetall default environment variables from the image or from built-in or containers.conf
UnsetEnvAll unsets all default environment variables from the image or from built-in
Optional.
type: boolean
x-go-name: UnsetEnvAll
utsns:
$ref: '#/definitions/Namespace'
title: ContainerBasicConfig contains the basic parts of a container.
type: object
x-go-package: go.podman.io/podman/v6/pkg/specgen
ContainerCgroupConfig:
description: |-
ContainerCgroupConfig contains configuration information about a container's
# --- truncated at 32 KB (739 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/podman/refs/heads/main/openapi/podman-openapi.yml