OpenAPI Specification
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 pods 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 pods
name: pods
paths:
/libpod/generate/{name}/systemd:
get:
description: Generate Systemd Units based on a pod or container.
operationId: GenerateSystemdLibpod
parameters:
- description: Name or ID of the container or pod.
in: path
name: name
required: true
type: string
- default: false
description: Use container/pod names instead of IDs.
in: query
name: useName
type: boolean
- default: false
description: Create a new container instead of starting an existing one.
in: query
name: new
type: boolean
- default: false
description: Do not generate the header including the Podman version and the timestamp.
in: query
name: noHeader
type: boolean
- default: 0
description: Start timeout in seconds.
in: query
name: startTimeout
type: integer
- default: 10
description: Stop timeout in seconds.
in: query
name: stopTimeout
type: integer
- default: on-failure
description: Systemd restart-policy.
enum:
- 'no'
- on-success
- on-failure
- on-abnormal
- on-watchdog
- on-abort
- always
in: query
name: restartPolicy
type: string
- default: container
description: Systemd unit name prefix for containers.
in: query
name: containerPrefix
type: string
- default: pod
description: Systemd unit name prefix for pods.
in: query
name: podPrefix
type: string
- default: '-'
description: Systemd unit name separator between name/id and prefix.
in: query
name: separator
type: string
- default: 0
description: Configures the time to sleep before restarting a service.
in: query
name: restartSec
type: integer
- default: []
description: Systemd Wants list for the container or pods.
in: query
items:
type: string
name: wants
type: array
- default: []
description: Systemd After list for the container or pods.
in: query
items:
type: string
name: after
type: array
- default: []
description: Systemd Requires list for the container or pods.
in: query
items:
type: string
name: requires
type: array
- default: []
description: Set environment variables to the systemd unit files.
in: query
items:
type: string
name: additionalEnvVariables
type: array
- default: false
description: Add template specifier for the systemd unit file names.
in: query
name: templateUnitFile
type: boolean
produces:
- application/json
responses:
'200':
description: no error
schema:
additionalProperties:
type: string
type: object
'500':
$ref: '#/responses/internalError'
summary: Generate Systemd Units
tags:
- pods
/libpod/generate/kube:
get:
description: Generate Kubernetes YAML based on a pod or container.
operationId: GenerateKubeLibpod
parameters:
- description: Name or ID of the container or pod.
in: query
items:
type: string
name: names
required: true
type: array
- default: false
description: Generate YAML for a Kubernetes service object.
in: query
name: service
type: boolean
- default: pod
description: Generate YAML for the given Kubernetes kind.
in: query
name: type
type: string
- default: 0
description: Set the replica number for Deployment kind.
format: int32
in: query
name: replicas
type: integer
- default: false
description: don't truncate annotations to the Kubernetes maximum length of 63 characters
in: query
name: noTrunc
type: boolean
- default: false
description: add podman-only reserved annotations in generated YAML file (cannot be used by Kubernetes)
in: query
name: podmanOnly
type: boolean
produces:
- text/vnd.yaml
- application/json
responses:
'200':
description: Kubernetes YAML file describing pod
schema:
format: binary
type: string
'500':
$ref: '#/responses/internalError'
summary: Generate a Kubernetes YAML file.
tags:
- pods
/libpod/kube/apply:
post:
description: Deploy a podman container, pod, volume, or Kubernetes yaml to a Kubernetes cluster.
operationId: KubeApplyLibpod
parameters:
- description: Path to the CA cert file for the Kubernetes cluster.
in: query
name: caCertFile
type: string
- description: Path to the kubeconfig file for the Kubernetes cluster.
in: query
name: kubeConfig
type: string
- description: The namespace to deploy the workload to on the Kubernetes cluster.
in: query
name: namespace
type: string
- description: Create a service object for the container being deployed.
in: query
name: service
type: boolean
- description: Path to the Kubernetes yaml file to deploy.
in: query
name: file
type: string
- description: Kubernetes YAML file.
in: body
name: request
schema:
type: string
produces:
- application/json
responses:
'200':
description: Kubernetes YAML file successfully deployed to cluster
schema:
format: binary
type: string
'500':
$ref: '#/responses/internalError'
summary: Apply a podman workload or Kubernetes YAML file.
tags:
- pods
/libpod/play/kube:
delete:
description: Tears down pods, secrets, and volumes defined in a YAML file
operationId: PlayKubeDownLibpod
parameters:
- default: false
description: Remove volumes.
in: query
name: force
type: boolean
produces:
- application/json
responses:
'200':
$ref: '#/responses/playKubeResponseLibpod'
'500':
$ref: '#/responses/internalError'
summary: Remove resources created from kube play
tags:
- pods
post:
description: "Create and run pods based on a Kubernetes YAML file.\n\n### Content-Type\n\nThen endpoint support two Content-Type\n - `plain/text` for yaml format\n - `application/x-tar` for sending context(s) required for building images\n\n#### Tar format\n\nThe tar format must contain a `play.yaml` file at the root that will be used.\nIf the file format requires context to build an image, it uses the image name and\ncheck for corresponding folder.\n\nFor example, the client sends a tar file with the following structure:\n\n```\n└── content.tar\n ├── play.yaml\n └── foobar/\n └── Containerfile\n```\n\nThe `play.yaml` is the following, the `foobar` image means we are looking for a context with this name.\n```\napiVersion: v1\nkind: Pod\nmetadata:\nname: demo-build-remote\nspec:\ncontainers:\n - name: container\n image: foobar\n```\n"
operationId: PlayKubeLibpod
parameters:
- default: plain/text
enum:
- plain/text
- application/x-tar
in: header
name: Content-Type
type: string
- description: JSON encoded value of annotations (a map[string]string).
in: query
name: annotations
type: string
- description: Logging driver for the containers in the pod.
in: query
name: logDriver
type: string
- description: logging driver options
in: query
items:
type: string
name: logOptions
type: array
- description: USe the network mode or specify an array of networks.
in: query
items:
type: string
name: network
type: array
- default: false
description: do not setup /etc/hosts file in container
in: query
name: noHosts
type: boolean
- default: false
description: use annotations that are not truncated to the Kubernetes maximum length of 63 characters
in: query
name: noTrunc
type: boolean
- description: publish a container's port, or a range of ports, to the host
in: query
items:
type: string
name: publishPorts
type: array
- description: Whether to publish all ports defined in the K8S YAML file (containerPort, hostPort), if false only hostPort will be published
in: query
name: publishAllPorts
type: boolean
- default: false
description: replace existing pods and containers
in: query
name: replace
type: boolean
- default: false
description: Starts a service container before all pods.
in: query
name: serviceContainer
type: boolean
- default: true
description: Start the pod after creating it.
in: query
name: start
type: boolean
- description: Static IPs used for the pods.
in: query
items:
type: string
name: staticIPs
type: array
- description: Static MACs used for the pods.
in: query
items:
type: string
name: staticMACs
type: array
- default: true
description: Require HTTPS and verify signatures when contacting registries.
in: query
name: tlsVerify
type: boolean
- description: Set the user namespace mode for the pods.
in: query
name: userns
type: string
- default: false
description: Clean up all objects created when a SIGTERM is received or pods exit.
in: query
name: wait
type: boolean
- description: Build the images with corresponding context.
in: query
name: build
type: boolean
- description: Kubernetes YAML file.
in: body
name: request
schema:
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/playKubeResponseLibpod'
'500':
$ref: '#/responses/internalError'
summary: Play a Kubernetes YAML file.
tags:
- pods
/libpod/pods/{name}:
delete:
operationId: PodDeleteLibpod
parameters:
- description: the name or ID of the pod
in: path
name: name
required: true
type: string
- description: force removal of a running pod by first stopping all containers, then removing all containers in the pod
in: query
name: force
type: boolean
- description: number of seconds to wait before killing containers in pod
in: query
name: timeout
type: integer
produces:
- application/json
responses:
'200':
$ref: '#/responses/podRmResponse'
'400':
$ref: '#/responses/badParamError'
'404':
$ref: '#/responses/podNotFound'
'500':
$ref: '#/responses/internalError'
summary: Remove pod
tags:
- pods
/libpod/pods/{name}/exists:
get:
description: Check if a pod exists by name or ID
operationId: PodExistsLibpod
parameters:
- description: the name or ID of the pod
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'204':
description: pod exists
'404':
$ref: '#/responses/podNotFound'
'500':
$ref: '#/responses/internalError'
summary: Pod exists
tags:
- pods
/libpod/pods/{name}/json:
get:
operationId: PodInspectLibpod
parameters:
- description: the name or ID of the pod
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/podInspectResponse'
'404':
$ref: '#/responses/podNotFound'
'500':
$ref: '#/responses/internalError'
summary: Inspect pod
tags:
- pods
/libpod/pods/{name}/kill:
post:
operationId: PodKillLibpod
parameters:
- description: the name or ID of the pod
in: path
name: name
required: true
type: string
- default: SIGKILL
description: signal to be sent to pod
in: query
name: signal
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/podKillResponse'
'400':
$ref: '#/responses/badParamError'
'404':
$ref: '#/responses/podNotFound'
'409':
$ref: '#/responses/podKillResponse'
'500':
$ref: '#/responses/internalError'
summary: Kill a pod
tags:
- pods
/libpod/pods/{name}/pause:
post:
description: Pause a pod
operationId: PodPauseLibpod
parameters:
- description: the name or ID of the pod
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/podPauseResponse'
'404':
$ref: '#/responses/podNotFound'
'409':
$ref: '#/responses/podPauseResponse'
'500':
$ref: '#/responses/internalError'
summary: Pause a pod
tags:
- pods
/libpod/pods/{name}/restart:
post:
operationId: PodRestartLibpod
parameters:
- description: the name or ID of the pod
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/podRestartResponse'
'404':
$ref: '#/responses/podNotFound'
'409':
$ref: '#/responses/podRestartResponse'
'500':
$ref: '#/responses/internalError'
summary: Restart a pod
tags:
- pods
/libpod/pods/{name}/start:
post:
operationId: PodStartLibpod
parameters:
- description: the name or ID of the pod
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/podStartResponse'
'304':
$ref: '#/responses/podAlreadyStartedError'
'404':
$ref: '#/responses/podNotFound'
'409':
$ref: '#/responses/podStartResponse'
'500':
$ref: '#/responses/internalError'
summary: Start a pod
tags:
- pods
/libpod/pods/{name}/stop:
post:
operationId: PodStopLibpod
parameters:
- description: the name or ID of the pod
in: path
name: name
required: true
type: string
- description: timeout
in: query
name: t
type: integer
produces:
- application/json
responses:
'200':
$ref: '#/responses/podStopResponse'
'304':
$ref: '#/responses/podAlreadyStoppedError'
'400':
$ref: '#/responses/badParamError'
'404':
$ref: '#/responses/podNotFound'
'409':
$ref: '#/responses/podStopResponse'
'500':
$ref: '#/responses/internalError'
summary: Stop a pod
tags:
- pods
/libpod/pods/{name}/top:
get:
description: List processes running inside a pod
operationId: PodTopLibpod
parameters:
- description: Name of pod to query for processes
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
name: ps_args
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/podTopResponse'
'404':
$ref: '#/responses/podNotFound'
'500':
$ref: '#/responses/internalError'
summary: List processes
tags:
- pods
/libpod/pods/{name}/unpause:
post:
operationId: PodUnpauseLibpod
parameters:
- description: the name or ID of the pod
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/podUnpauseResponse'
'404':
$ref: '#/responses/podNotFound'
'409':
$ref: '#/responses/podUnpauseResponse'
'500':
$ref: '#/responses/internalError'
summary: Unpause a pod
tags:
- pods
/libpod/pods/create:
post:
operationId: PodCreateLibpod
parameters:
- description: attributes for creating a pod
in: body
name: create
schema:
$ref: '#/definitions/PodSpecGenerator'
produces:
- application/json
responses:
'201':
description: ''
schema:
$ref: '#/definitions/IDResponse'
'400':
$ref: '#/responses/badParamError'
'409':
description: status conflict
schema:
description: message describing error
type: string
'500':
$ref: '#/responses/internalError'
summary: Create a pod
tags:
- pods
/libpod/pods/json:
get:
operationId: PodListLibpod
parameters:
- description: "JSON encoded value of the filters (a map[string][]string) to process on the pods list. Available filters:\n - `id=<pod-id>` Matches all of pod id.\n - `label=<key>` or `label=<key>:<value>` Matches pods based on the presence of a label alone or a label and a value.\n - `name=<pod-name>` Matches all of pod name.\n - `until=<timestamp>` List pods 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 - `status=<pod-status>` Pod's status: `stopped`, `running`, `paused`, `exited`, `dead`, `created`, `degraded`.\n - `network=<pod-network>` Name or full ID of network.\n - `ctr-names=<pod-ctr-names>` Container name within the pod.\n - `ctr-ids=<pod-ctr-ids>` Container ID within the pod.\n - `ctr-status=<pod-ctr-status>` Container status within the pod.\n - `ctr-number=<pod-ctr-number>` Number of containers in the pod.\n"
in: query
name: filters
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/podsListResponse'
'400':
$ref: '#/responses/badParamError'
'500':
$ref: '#/responses/internalError'
summary: List pods
tags:
- pods
/libpod/pods/prune:
post:
operationId: PodPruneLibpod
produces:
- application/json
responses:
'200':
$ref: '#/responses/podPruneResponse'
'400':
$ref: '#/responses/badParamError'
'409':
description: pod already exists
'500':
$ref: '#/responses/internalError'
summary: Prune unused pods
tags:
- pods
/libpod/pods/stats:
get:
description: Display a live stream of resource usage statistics for the containers in one or more pods
operationId: PodStatsAllLibpod
parameters:
- description: Provide statistics for all running pods.
in: query
name: all
type: boolean
- description: Names or IDs of pods.
in: query
items:
type: string
name: namesOrIDs
type: array
- default: false
description: Stream the output
in: query
name: stream
type: boolean
- default: 5
description: Time in seconds between stats reports
in: query
name: delay
type: integer
produces:
- application/json
responses:
'200':
$ref: '#/responses/podStatsResponse'
'404':
$ref: '#/responses/podNotFound'
'500':
$ref: '#/responses/internalError'
summary: Statistics for one or more pods
tags:
- pods
definitions:
InspectPodData:
description: 'InspectPodData contains detailed information on a pod''s configuration and
state. It is used as the output of Inspect on pods.'
properties:
CgroupParent:
description: CgroupParent is the parent of the pod's Cgroup.
type: string
CgroupPath:
description: CgroupPath is the path to the pod's Cgroup.
type: string
Containers:
description: 'Containers gives a brief summary of all containers in the pod and
their current status.'
items:
$ref: '#/definitions/InspectPodContainerInfo'
type: array
CreateCgroup:
description: 'CreateCgroup is whether this pod will create its own Cgroup to group
containers under.'
type: boolean
CreateCommand:
description: 'CreateCommand is the full command plus arguments of the process the
container has been created with.'
items:
type: string
type: array
CreateInfra:
description: 'CreateInfra is whether this pod will create an infra container to
share namespaces.'
type: boolean
Created:
description: Created is the time when the pod was created.
format: date-time
type: string
ExitPolicy:
description: ExitPolicy of the pod.
type: string
Hostname:
description: Hostname is the hostname that the pod will set.
type: string
Id:
description: ID is the ID of the pod.
type: string
x-go-name: ID
InfraConfig:
$ref: '#/definitions/InspectPodInfraConfig'
InfraContainerID:
description: 'InfraContainerID is the ID of the pod''s infra container, if one is
present.'
type: string
Labels:
additionalProperties:
type: string
description: 'Labels is a set of key-value labels that have been applied to the
pod.'
type: object
LockNumber:
description: Number of the pod's Libpod lock.
format: uint32
type: integer
Name:
description: Name is the name of the pod.
type: string
Namespace:
description: Namespace is the Libpod namespace the pod is placed in.
type: string
NumContainers:
description: 'NumContainers is the number of containers in the pod, including the
infra container.'
format: uint64
type: integer
RestartPolicy:
description: RestartPolicy of the pod.
type: string
SharedNamespaces:
description: 'SharedNamespaces contains a list of namespaces that will be shared by
containers within the pod. Can only be set if CreateInfra is true.'
items:
type: string
type: array
State:
description: State represents the current state of the pod.
type: string
blkio_weight:
description: BlkioWeight contains the blkio weight limit for the pod
format: uint64
type: integer
x-go-name: BlkioWeight
blkio_weight_device:
description: BlkioWeightDevice contains the blkio weight device limits for the pod
items:
$ref: '#/definitions/InspectBlkioWeightDevice'
type: array
x-go-name: BlkioWeightDevice
cpu_period:
description: CPUPeriod contains the CPU period of the pod
format: uint64
type: integer
x-go-name: CPUPeriod
cpu_quota:
description: CPUQuota contains the CPU quota of the pod
format: int64
type: integer
x-go-name: CPUQuota
cpu_shares:
description: CPUShares contains the cpu shares for the pod
format: uint64
type: integer
x-go-name: CPUShares
cpuset_cpus:
description: CPUSetCPUs contains linux specific CPU data for the pod
type: string
x-go-name: CPUSetCPUs
cpuset_mems:
description: CPUSetMems contains linux specific CPU data for the pod
type: string
x-go-name: CPUSetMems
device_read_bps:
description: BlkioDeviceReadBps contains the Read/Access limit for the pod's devices
items:
$ref: '#/definitions/InspectBlkioThrottleDevice'
type: array
x-go-name: BlkioDeviceReadBps
device_write_bps:
description: BlkioDeviceReadBps contains the Read/Access limit for the pod's devices
items:
$ref: '#/definitions/InspectBlkioThrottleDevice'
type: array
x-go-name: BlkioDeviceWriteBps
devices:
description: Devices contains the specified host devices
items:
$ref: '#/definitions/InspectDevice'
type: array
x-go-name: Devices
memory_limit:
description: MemoryLimit contains the specified cgroup memory limit for the pod
format: uint64
type: integer
x-go-name: MemoryLimit
memory_swap:
description: MemorySwap contains the specified memory swap limit for the pod
format: uint64
type: integer
x-go-name: MemorySwap
mounts:
description: Mounts contains volume related information for the pod
items:
$ref: '#/definitions/InspectMount'
type: array
x-go-name: Mounts
security_opt:
description: SecurityOpt contains the specified security labels and related SELinux information
items:
type: string
type: array
x-go-name: SecurityOpts
volumes_from:
description: VolumesFrom contains the containers that the pod inherits mounts from
items:
type: string
type: array
x-go-name: VolumesFrom
type: object
x-go-package: go.podman.io/podman/v6/libpod/define
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
LinuxDeviceCgroup:
description: 'LinuxDeviceCgroup represents a device rule for the devices specified to
the device controller'
properties:
access:
description: Cgroup access permissions format, rwm.
type: string
x-go-name: Access
allow:
description: Allow or deny
type: boolean
x-go-name: Allow
major:
description: Major is the device's major number.
format: int64
type: integer
x-go-name: Major
minor:
description: Minor is the device's minor number.
format: int64
type: integer
x-go-name: Minor
type:
description: Device type, block, char, etc.
type: string
x-go-name: Type
type: object
x-go-package: github.com/opencontainers/runtime-spec/specs-go
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
ClusterOptions:
title: ClusterOptions specifies options for a Cluster volume.
type: object
x-go-package: github.com/moby/moby/api/types/mount
PortMapping:
properties:
container_port:
description: 'ContainerPort is the port number that will be exposed from the
container.
Mandatory.'
format: uint16
type: integer
x-go-name: ContainerPort
host_ip:
description: 'HostIP is the IP that we will bind to on the host.
If unset, assumed to be
# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/podman/refs/heads/main/openapi/podman-pods-api-openapi.yml