Documentation Powered by ReDoc

Provides a container compatible interface. (0.0.1)

Download OpenAPI specification:Download

Podman: podman@lists.podman.io URL: https://podman.io/community/ License: Apache-2.0

This documentation describes the Podman v2.0 RESTful API. It replaces the Podman v1.0 API and was initially delivered along with Podman v2.0. 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

See podman-service(1) for more information.

Quick Examples:

'podman info'

curl --unix-socket /run/podman/podman.sock http://d/v1.0.0/libpod/info

'podman pull quay.io/containers/podman'

curl -XPOST --unix-socket /run/podman/podman.sock -v 'http://d/v1.0.0/images/create?fromImage=quay.io%2Fcontainers%2Fpodman'

'podman list images'

curl --unix-socket /run/podman/podman.sock -v 'http://d/v1.0.0/libpod/images/json' | jq

containers

Actions related to containers

Commit

Create a new image from a container

query Parameters
container
required
string

the name or ID of a container

repo
string

the repository name for the created image

tag
string

tag name for the created image

comment
string

commit message

author
string

author of the image

pause
boolean

pause the container before committing it

changes
Array of strings

instructions to apply while committing in Dockerfile format (i.e. "CMD=/bin/foo")

format
string

format of the image manifest and metadata (default "oci")

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Run a container's healthcheck

Execute the defined healthcheck and return information about the results

path Parameters
name:.*
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "FailingStreak": 0,
  • "Log": [
    ],
  • "Status": "string"
}

Delete container

Delete container

path Parameters
name
required
string

the name or ID of the container

query Parameters
force
boolean

need something

v
boolean

delete volumes

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Copy files into a container

Copy a tar archive of files into a container

path Parameters
name
required
string

container name or id

query Parameters
path
required
string

Path to a directory in the container to extract

pause
boolean
Default: true

pause the container while copying (defaults to true)

Request Body schema:
application/json
application/json
application/x-tar

tarfile of files to copy into the container

string

Responses

Request samples

Content type
application/json
application/json
application/x-tar
"string"

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Attach to a container

Hijacks the connection to forward the container's standard streams to the client.

path Parameters
name
required
string

the name or ID of the container

query Parameters
detachKeys
string

keys to use for detaching from the container

logs
boolean

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

stream
boolean
Default: true

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

stdout
boolean

Attach to container STDOUT

stderr
boolean

Attach to container STDERR

stdin
boolean

Attach to container STDIN

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Report on changes to container's filesystem; adds, deletes or modifications.

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

path Parameters
name
required
string

the name or id of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Checkpoint a container

path Parameters
name
required
string

the name or ID of the container

query Parameters
keep
boolean

keep all temporary checkpoint files

leaveRunning
boolean

leave the container running after writing checkpoint to disk

tcpEstablished
boolean

checkpoint a container with established TCP connections

export
boolean

export the checkpoint image to a tar.gz

ignoreRootFS
boolean

do not include root file-system changes when exporting

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Check if container exists

Quick way to determine if a container exists by name or ID

path Parameters
name
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Export a container

Export the contents of a container as a tarball.

path Parameters
name
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Initialize a container

Performs all tasks necessary for initializing the container but does not start the container.

path Parameters
name
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Inspect container

Return low-level information about a container.

path Parameters
name
required
string

the name or ID of the container

query Parameters
size
boolean

display filesystem usage

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "AppArmorProfile": "string",
  • "Args": [
    ],
  • "BoundingCaps": [
    ],
  • "Config": {
    },
  • "ConmonPidFile": "string",
  • "Created": "2019-08-24T14:15:22Z",
  • "Dependencies": [
    ],
  • "Driver": "string",
  • "EffectiveCaps": [
    ],
  • "ExecIDs": [
    ],
  • "ExitCommand": [
    ],
  • "GraphDriver": {
    },
  • "HostConfig": {
    },
  • "HostnamePath": "string",
  • "HostsPath": "string",
  • "Id": "string",
  • "Image": "string",
  • "ImageName": "string",
  • "IsInfra": true,
  • "MountLabel": "string",
  • "Mounts": [
    ],
  • "Name": "string",
  • "Namespace": "string",
  • "NetworkSettings": {
    },
  • "OCIConfigPath": "string",
  • "OCIRuntime": "string",
  • "Path": "string",
  • "Pod": "string",
  • "ProcessLabel": "string",
  • "ResolvConfPath": "string",
  • "RestartCount": 0,
  • "Rootfs": "string",
  • "SizeRootFs": 0,
  • "SizeRw": 0,
  • "State": {
    },
  • "StaticDir": "string"
}

Kill container

send a signal to a container, defaults to killing the container

path Parameters
name
required
string

the name or ID of the container

query Parameters
signal
string
Default: "TERM"

signal to be sent to container, either by integer or SIG_ name

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Get container logs

Get stdout and stderr logs from a container.

path Parameters
name
required
string

the name or ID of the container

query Parameters
follow
boolean

Keep connection after returning logs.

stdout
boolean

Return logs from stdout

stderr
boolean

Return logs from stderr

since
string

Only return logs since this time, as a UNIX timestamp

until
string

Only return logs before this time, as a UNIX timestamp

timestamps
boolean
Default: false

Add timestamps to every log line

tail
string
Default: "all"

Only return this number of log lines from the end of the logs

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Mount a container

Mount a container to the filesystem

path Parameters
name
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
"/var/lib/containers/storage/overlay/f3f693bd88872a1e3193f4ebb925f4c282e8e73aadb8ab3e7492754dda3a02a4/merged"

Pause a container

Use the cgroups freezer to suspend all processes in a container.

path Parameters
name
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Rename an existing container

Change the name of an existing container.

path Parameters
name
required
string

Full or partial ID or full name of the container to rename

query Parameters
name
required
string

New name for the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Resize a container's TTY

Resize the terminal attached to a container (for use with Attach).

path Parameters
name
required
string

the name or ID of the container

query Parameters
h
integer

Height to set for the terminal, in characters

w
integer

Width to set for the terminal, in characters

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{ }

Restart a container

path Parameters
name
required
string

the name or ID of the container

query Parameters
t
integer

timeout before sending kill signal to container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Restore a container

Restore a container from a checkpoint.

path Parameters
name
required
string

the name or id of the container

query Parameters
name
string

the name of the container when restored from a tar. can only be used with import

keep
boolean

keep all temporary checkpoint files

leaveRunning
boolean

leave the container running after writing checkpoint to disk

tcpEstablished
boolean

checkpoint a container with established TCP connections

import
boolean

import the restore from a checkpoint tar.gz

ignoreRootFS
boolean

do not include root file-system changes when exporting

ignoreStaticIP
boolean

ignore IP address if set statically

ignoreStaticMAC
boolean

ignore MAC address if set statically

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Start a container

path Parameters
name
required
string

the name or ID of the container

query Parameters
detachKeys
string
Default: "ctrl-p,ctrl-q"

Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl- where is one of: a-z, @, ^, [, , or _.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Get stats for a container

DEPRECATED. This endpoint will be removed with the next major release. Please use /libpod/containers/stats instead.

path Parameters
name
required
string

the name or ID of the container

query Parameters
stream
boolean
Default: true

Stream the output

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Stop a container

path Parameters
name
required
string

the name or ID of the container

query Parameters
t
integer

number of seconds to wait before killing container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

List processes

List processes running inside a container

path Parameters
name
required
string

Name of container to query for processes (As of version 1.xx)

query Parameters
stream
boolean
Default: true

Stream the output

ps_args
string
Default: "-ef"

arguments to pass to ps such as aux. Requires ps(1) to be installed in the container if no ps(1) compatible AIX descriptors are used.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Processes": [
    ],
  • "Titles": [
    ]
}

Unmount a container

Unmount a container from the filesystem

path Parameters
name
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Unpause Container

path Parameters
name
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Wait on a container

Wait on a container to met a given condition

path Parameters
name
required
string

the name or ID of the container

query Parameters
condition
string

wait until container is to a given condition. default is stopped. valid conditions are:

  • configured
  • created
  • exited
  • paused
  • running
  • stopped

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Error": {
    },
  • "StatusCode": 0
}

Create a container

Request Body schema:
application/json
application/json
application/x-tar

attributes for creating a container

object

Aliases are a list of network-scoped aliases for container Optional

object

Annotations are key-value options passed into the container runtime that can be used to trigger special behavior. Optional.

apparmor_profile
string

ApparmorProfile is the name of the Apparmor profile the container will use. Optional.

cap_add
Array of strings

CapAdd are capabilities which will be added to the container. Conflicts with Privileged. Optional.

cap_drop
Array of strings

CapDrop are capabilities which will be removed from the container. Conflicts with Privileged. Optional.

cgroup_parent
string

CgroupParent is the container's CGroup parent. If not set, the default for the current cgroup driver will be used. Optional.

object (Namespace)

Namespace describes the namespace

cgroups_mode
string

CgroupsMode sets a policy for how cgroups will be created in the container, including the ability to disable creation entirely.

cni_networks
Array of strings

CNINetworks is a list of CNI networks to join the container to. If this list is empty, the default CNI network will be joined instead. If at least one entry is present, we will not join the default network (unless it is part of this list). Only available if NetNS is set to bridge. Optional.

command
Array of strings

Command is the container's command. If not given and Image is specified, this will be populated by the image's configuration. Optional.

conmon_pid_file
string

ConmonPidFile is a path at which a PID file for Conmon will be placed. If not given, a default location will be used. Optional.

containerCreateCommand
Array of strings

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.

Array of objects (LinuxDevice)

Devices are devices that will be added to the container. Optional.

dns_option
Array of strings

DNSOptions is a set of DNS options that will be used in the container's resolv.conf, replacing the host's DNS options which are used by default. Conflicts with UseImageResolvConf. Optional.

dns_search
Array of strings

DNSSearch is a set of DNS search domains that will be used in the container's resolv.conf, replacing the host's DNS search domains which are used by default. Conflicts with UseImageResolvConf. Optional.

dns_server
Array of Array of integers (An IP is a single IP address, a slice of bytes. Functions in this package accept either 4-byte (IPv4) or 16-byte (IPv6) slices as input.)

DNSServers is a set of DNS servers that will be used in the container's resolv.conf, replacing the host's DNS Servers which are used by default. Conflicts with UseImageResolvConf. Optional.

entrypoint
Array of strings

Entrypoint is the container's entrypoint. If not given and Image is specified, this will be populated by the image's configuration. Optional.

object

Env is a set of environment variables that will be set in the container. Optional.

env_host
boolean

EnvHost indicates that the host environment should be added to container Optional.

expose
any

Expose is a number of ports that will be forwarded to the container if PublishExposedPorts is set. Expose is a map of uint16 (port number) to a string representing protocol. Allowed protocols are "tcp", "udp", and "sctp", or some combination of the three separated by commas. If protocol is set to "" we will assume TCP. Only available if NetNS is set to Bridge or Slirp, and PublishExposedPorts is set. Optional.

groups
Array of strings

Groups are a list of supplemental groups the container's user will be granted access to. Optional.

object (Schema2HealthConfig)

Schema2HealthConfig is a HealthConfig, which holds configuration settings for the HEALTHCHECK feature, from docker/docker/api/types/container.

hostadd
Array of strings

HostAdd is a set of hosts which will be added to the container's etc/hosts file. Conflicts with UseImageHosts. Optional.

hostname
string

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.

httpproxy
boolean

EnvHTTPProxy indicates that the http host proxy environment variables should be added to container Optional.

object (IDMappingOptions)

IDMappingOptions are used for specifying how ID mapping should be set up for a layer or container.

image
string

Image is the image the container will be based on. The image will be used as the container's root filesystem, and its environment vars, volumes, and other configuration will be applied to the container. Conflicts with Rootfs. At least one of Image or Rootfs must be specified.

image_volume_mode
string

ImageVolumeMode indicates how image volumes will be created. Supported modes are "ignore" (do not create), "tmpfs" (create as tmpfs), and "anonymous" (create as anonymous volumes). The default if unset is anonymous. Optional.

Array of objects (ImageVolume)

Image volumes bind-mount a container-image mount into the container. Optional.

init
boolean

Init specifies that an init binary will be mounted into the container, and will be used as PID1.

init_path
string

InitPath specifies the path to the init binary that will be added if Init is specified above. If not specified, the default set in the Libpod config will be used. Ignored if Init above is not set. Optional.

object (Namespace)

Namespace describes the namespace

object

Labels are key-value pairs that are used to add metadata to containers. Optional.

object (LogConfig)

LogConfig describes the logging characteristics for a container

mask
Array of strings

Mask is the path we want to mask in the container. This masks the paths given in addition to the default list. Optional

Array of objects (Mount specifies a mount for a container.)

Mounts are mounts that will be added to the container. These will supersede Image Volumes and VolumesFrom volumes where there are conflicts. Optional.

name
string

Name is the name the container will be given. If no name is provided, one will be randomly generated. Optional.

namespace
string

Namespace is the libpod namespace the container will be placed in. Optional.

object (Namespace)

Namespace describes the namespace

object

NetworkOptions are additional options for each network Optional.

no_new_privileges
boolean

NoNewPrivileges is whether the container will set the no new privileges flag on create, which disables gaining additional privileges (e.g. via setuid) in the container.

oci_runtime
string

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.

oom_score_adj
integer <int64>

OOMScoreAdj adjusts the score used by the OOM killer to determine processes to kill for the container's process. Optional.

Array of objects (OverlayVolume)

Overlay volumes are named volumes that will be added to the container. Optional.

object (Namespace)

Namespace describes the namespace

pod
string

Pod is the ID of the pod the container will join. Optional.

Array of objects (PortMapping is one or more ports that will be mapped into the container.)

PortBindings is a set of ports to map into the container. Only available if NetNS is set to bridge or slirp. Optional.

privileged
boolean

Privileged is whether the container is privileged. Privileged does the following: Adds all devices on the system to the container. Adds all capabilities to the container. Disables Seccomp, SELinux, and Apparmor confinement. (Though SELinux can be manually re-enabled). TODO: this conflicts with things. TODO: this does more.

procfs_opts
Array of strings

ProcOpts are the options used for the proc mount.

publish_image_ports
boolean

PublishExposedPorts will publish ports specified in the image to random unused ports (guaranteed to be above 1024) on the host. This is based on ports set in Expose below, and any ports specified by the Image (if one is given). Only available if NetNS is set to Bridge or Slirp.

Array of objects (POSIXRlimit)

Rlimits are POSIX rlimits to apply to the container. Optional.

raw_image_name
string

RawImageName is the user-specified and unprocessed input referring to a local or a remote image.

read_only_filesystem
boolean

ReadOnlyFilesystem indicates that everything will be mounted as read-only

remove
boolean

Remove indicates if the container should be removed once it has been started and exits

object (LinuxResources)

LinuxResources has container runtime resource constraints

restart_policy
string

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.

restart_tries
integer <uint64>

RestartRetries is the number of attempts that will be made to restart the container. Only available when RestartPolicy is set to "on-failure". Optional.

rootfs
string

Rootfs is the path to a directory that will be used as the container's root filesystem. No modification will be made to the directory, it will be directly mounted into the container as root. Conflicts with Image. At least one of Image or Rootfs must be specified.

rootfs_propagation
string

RootfsPropagation is the rootfs propagation mode for the container. If not set, the default of rslave will be used. Optional.

sdnotifyMode
string

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

seccomp_policy
string

SeccompPolicy determines which seccomp profile gets applied the container. valid values: empty,default,image

seccomp_profile_path
string

SeccompProfilePath is the path to a JSON file containing the container's Seccomp profile. If not specified, no Seccomp profile will be used. Optional.

selinux_opts
Array of strings

SelinuxProcessLabel is the process label the container will use. If SELinux is enabled and this is not specified, a label will be automatically generated if not specified. Optional.

shm_size
integer <int64>

ShmSize is the size of the tmpfs to mount in at /dev/shm, in bytes. Conflicts with ShmSize if IpcNS is not private. Optional.

static_ip
Array of integers <uint8> (An IP is a single IP address, a slice of bytes. Functions in this package accept either 4-byte (IPv4) or 16-byte (IPv6) slices as input.)

Note that in this documentation, referring to an IP address as an IPv4 address or an IPv6 address is a semantic property of the address, not just the length of the byte slice: a 16-byte slice can still be an IPv4 address.

static_ipv6
Array of integers <uint8> (An IP is a single IP address, a slice of bytes. Functions in this package accept either 4-byte (IPv4) or 16-byte (IPv6) slices as input.)

Note that in this documentation, referring to an IP address as an IPv4 address or an IPv6 address is a semantic property of the address, not just the length of the byte slice: a 16-byte slice can still be an IPv4 address.

static_mac
Array of integers <uint8> (A HardwareAddr represents a physical hardware address.)
stdin
boolean

Stdin is whether the container will keep its STDIN open.

stop_signal
integer <int64> (A Signal is a number describing a process signal.)

It implements the os.Signal interface.

stop_timeout
integer <uint64>

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.

object

Sysctl sets kernel parameters for the container

systemd
string

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.

terminal
boolean

Terminal is whether the container will create a PTY. Optional.

object

IO read rate limit per cgroup per device, bytes per second

object

IO read rate limit per cgroup per device, IO per second

object

IO write rate limit per cgroup per device, bytes per second

object

IO write rate limit per cgroup per device, IO per second

timezone
string

Timezone is the timezone inside the container. Local means it has the same timezone as the host machine

umask
string

Umask is the umask the init process of the container will be run with.

object

CgroupConf are key-value options passed into the container runtime that are used to configure cgroup v2. Optional.

unmask
Array of strings

Unmask is the path we want to unmask in the container. To override all the default paths that are masked, set unmask=ALL.

use_image_hosts
boolean

UseImageHosts indicates that /etc/hosts should not be managed by Podman, and instead sourced from the image. Conflicts with HostAdd.

use_image_resolve_conf
boolean

UseImageResolvConf indicates that resolv.conf should not be managed by Podman, but instead sourced from the image. Conflicts with DNSServer, DNSSearch, DNSOption.

user
string

User is the user the container will be run as. Can be given as a UID or a username; if a username, it will be resolved within the container, using the container's /etc/passwd. If unset, the container will be run as root. Optional.

object (Namespace)

Namespace describes the namespace

object (Namespace)

Namespace describes the namespace

Array of objects (NamedVolume)

Volumes are named volumes that will be added to the container. These will supersede Image Volumes and VolumesFrom volumes where there are conflicts. Optional.

volumes_from
Array of strings

VolumesFrom is a set of containers whose volumes will be added to this container. The name or ID of the container must be provided, and may optionally be followed by a : and then one or more comma-separated options. Valid options are 'ro', 'rw', and 'z'. Options will be used for all volumes sourced from the container.

object

Weight per cgroup per device, can override BlkioWeight

work_dir
string

WorkDir is the container's working directory. If unset, the default, /, will be used. Optional.

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "aliases": {
    },
  • "annotations": {
    },
  • "apparmor_profile": "string",
  • "cap_add": [
    ],
  • "cap_drop": [
    ],
  • "cgroup_parent": "string",
  • "cgroupns": {
    },
  • "cgroups_mode": "string",
  • "cni_networks": [
    ],
  • "command": [
    ],
  • "conmon_pid_file": "string",
  • "containerCreateCommand": [
    ],
  • "devices": [
    ],
  • "dns_option": [
    ],
  • "dns_search": [
    ],
  • "dns_server": [
    ],
  • "entrypoint": [
    ],
  • "env": {
    },
  • "env_host": true,
  • "expose": null,
  • "groups": [
    ],
  • "healthconfig": {
    },
  • "hostadd": [
    ],
  • "hostname": "string",
  • "httpproxy": true,
  • "idmappings": {
    },
  • "image": "string",
  • "image_volume_mode": "string",
  • "image_volumes": [
    ],
  • "init": true,
  • "init_path": "string",
  • "ipcns": {
    },
  • "labels": {
    },
  • "log_configuration": {
    },
  • "mask": [
    ],
  • "mounts": [
    ],
  • "name": "string",
  • "namespace": "string",
  • "netns": {
    },
  • "network_options": {
    },
  • "no_new_privileges": true,
  • "oci_runtime": "string",
  • "oom_score_adj": 0,
  • "overlay_volumes": [
    ],
  • "pidns": {
    },
  • "pod": "string",
  • "portmappings": [
    ],
  • "privileged": true,
  • "procfs_opts": [
    ],
  • "publish_image_ports": true,
  • "r_limits": [
    ],
  • "raw_image_name": "string",
  • "read_only_filesystem": true,
  • "remove": true,
  • "resource_limits": {
    },
  • "restart_policy": "string",
  • "restart_tries": 0,
  • "rootfs": "string",
  • "rootfs_propagation": "string",
  • "sdnotifyMode": "string",
  • "seccomp_policy": "string",
  • "seccomp_profile_path": "string",
  • "selinux_opts": [
    ],
  • "shm_size": 0,
  • "static_ip": [
    ],
  • "static_ipv6": [
    ],
  • "static_mac": [
    ],
  • "stdin": true,
  • "stop_signal": 0,
  • "stop_timeout": 0,
  • "sysctl": {
    },
  • "systemd": "string",
  • "terminal": true,
  • "throttleReadBpsDevice": {
    },
  • "throttleReadIOPSDevice": {
    },
  • "throttleWriteBpsDevice": {
    },
  • "throttleWriteIOPSDevice": {
    },
  • "timezone": "string",
  • "umask": "string",
  • "unified": {
    },
  • "unmask": [
    ],
  • "use_image_hosts": true,
  • "use_image_resolve_conf": true,
  • "user": "string",
  • "userns": {
    },
  • "utsns": {
    },
  • "volumes": [
    ],
  • "volumes_from": [
    ],
  • "weightDevice": {
    },
  • "work_dir": "string"
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Id": "string",
  • "Warnings": [
    ]
}

List containers

Returns a list of containers

query Parameters
all
boolean
Default: false

Return all containers. By default, only running containers are shown

limit
integer

Return this number of most recently created containers, including non-running ones.

pod
boolean
Default: false

Ignored. Previously included details on pod name and ID that are currently included by default.

size
boolean
Default: false

Return the size of container as fields SizeRw and SizeRootFs.

sync
boolean
Default: false

Sync container state with OCI runtime

filters
string

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 an container label
  • name=<name> a container's name
  • network=(<network id> or <network name>)
  • pod=(<pod id> or <pod 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>)

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Delete stopped containers

Remove containers not in use

query Parameters
filters
string

Filters to process on the prune list, encoded as JSON (a map[string][]string). Available filters:

  • 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.
  • 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.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Show mounted containers

Lists all mounted containers mount points

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Get stats for one or more containers

Return a live stream of resource usage statistics of one or more container. If no container is specified, the statistics of all containers are returned.

query Parameters
containers
Array of strings

names or IDs of containers

stream
boolean
Default: true

Stream the output

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Generate Systemd Units

Generate Systemd Units based on a pod or container.

path Parameters
name:.*
required
string

Name or ID of the container or pod.

query Parameters
useName
boolean
Default: false

Use container/pod names instead of IDs.

new
boolean
Default: false

Create a new container instead of starting an existing one.

time
integer
Default: 10

Stop timeout override.

restartPolicy
string
Default: "on-failure"
Enum: "no" "on-success" "on-failure" "on-abnormal" "on-watchdog" "on-abort" "always"

Systemd restart-policy.

containerPrefix
string
Default: "container"

Systemd unit name prefix for containers.

podPrefix
string
Default: "pod"

Systemd unit name prefix for pods.

separator
string
Default: "-"

Systemd unit name separator between name/id and prefix.

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Generate a Kubernetes YAML file.

Generate Kubernetes YAML based on a pod or container.

query Parameters
names
required
Array of strings

Name or ID of the container or pod.

service
boolean
Default: false

Generate YAML for a Kubernetes service object.

Responses

Response samples

Content type
application/json
"string"

Play a Kubernetes YAML file.

Create and run pods based on a Kubernetes YAML file (pod or service kind).

query Parameters
network
string

Connect the pod to this network.

tlsVerify
boolean
Default: true

Require HTTPS and verify signatures when contacting registries.

logDriver
string

Logging driver for the containers in the pod.

start
boolean
Default: true

Start the pod after creating it.

Request Body schema:
application/json
application/json
application/x-tar

Kubernetes YAML file.

string

Responses

Request samples

Content type
application/json
application/json
application/x-tar
"string"

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Pods": [
    ]
}

exec

Actions related to exec

Create an exec instance

Create an exec session to run a command inside a running container. Exec sessions will be automatically removed 5 minutes after they exit.

path Parameters
name
required
string

name of container

Request Body schema:
application/json
application/json
application/x-tar

Attributes for create

AttachStderr
boolean

Attach to stderr of the exec command

AttachStdin
boolean

Attach to stdin of the exec command

AttachStdout
boolean

Attach to stdout of the exec command

Cmd
Array of strings

Command to run, as a string or array of strings.

DetachKeys
string

"Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl- where is one of: a-z, @, ^, [, , or _."

Env
Array of strings

A list of environment variables in the form ["VAR=value", ...]

Privileged
boolean
Default: false

Runs the exec process with extended privileges

Tty
boolean

Allocate a pseudo-TTY

User
string

"The user, and optionally, group to run the exec process inside the container. Format is one of: user, user:group, uid, or uid:gid."

WorkingDir
string

The working directory for the exec process inside the container.

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "AttachStderr": true,
  • "AttachStdin": true,
  • "AttachStdout": true,
  • "Cmd": [
    ],
  • "DetachKeys": "string",
  • "Env": [
    ],
  • "Privileged": false,
  • "Tty": true,
  • "User": "string",
  • "WorkingDir": "string"
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Inspect an exec instance

Return low-level information about an exec instance.

path Parameters
id
required
string

Exec instance ID

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if tty was specified as part of creating and starting the exec instance.

path Parameters
id
required
string

Exec instance ID

query Parameters
h
integer

Height of the TTY session in characters

w
integer

Width of the TTY session in characters

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

path Parameters
id
required
string

Exec instance ID

Request Body schema:
application/json
application/json
application/x-tar

Attributes for start

Detach
boolean

Detach from the command. Not presently supported.

Tty
boolean

Allocate a pseudo-TTY. Presently ignored.

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "Detach": true,
  • "Tty": true
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

images

Actions related to images

Create image

Build an image from the given Dockerfile(s)

query Parameters
dockerfile
string
Default: "Dockerfile"

Path within the build context to the Dockerfile. This is ignored if remote is specified and points to an external Dockerfile.

t
string
Default: "latest"

A name and optional tag to apply to the image in the name:tag format. If you omit the tag the default latest value is assumed. You can provide several t parameters.

extrahosts
string

TBD Extra hosts to add to /etc/hosts (As of version 1.xx)

remote
string

A Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called Dockerfile and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the dockerfile parameter is also specified, there must be a file with the corresponding path inside the tarball. (As of version 1.xx)

q
boolean
Default: false

Suppress verbose build output

nocache
boolean
Default: false

Do not use the cache when building the image (As of version 1.xx)

cachefrom
string

JSON array of images used to build cache resolution (As of version 1.xx)

pull
boolean
Default: false

Attempt to pull the image even if an older image exists locally (As of version 1.xx)

rm
boolean
Default: true

Remove intermediate containers after a successful build (As of version 1.xx)

forcerm
boolean
Default: false

Always remove intermediate containers, even upon failure (As of version 1.xx)

memory
integer

Memory is the upper limit (in bytes) on how much memory running containers can use (As of version 1.xx)

memswap
integer

MemorySwap limits the amount of memory and swap together (As of version 1.xx)

cpushares
integer

CPUShares (relative weight (As of version 1.xx)

cpusetcpus
string

CPUSetCPUs in which to allow execution (0-3, 0,1) (As of version 1.xx)

cpuperiod
integer

CPUPeriod limits the CPU CFS (Completely Fair Scheduler) period (As of version 1.xx)

cpuquota
integer

CPUQuota limits the CPU CFS (Completely Fair Scheduler) quota (As of version 1.xx)

buildargs
string

JSON map of string pairs denoting build-time variables. For example, the build argument Foo with the value of bar would be encoded in JSON as ["Foo":"bar"].

For example, buildargs={"Foo":"bar"}.

Note(s):

  • This should not be used to pass secrets.
  • The value of buildargs should be URI component encoded before being passed to the API.

(As of version 1.xx)

shmsize
integer
Default: 67108864

ShmSize is the "size" value to use when mounting an shmfs on the container's /dev/shm directory. Default is 64MB (As of version 1.xx)

squash
boolean
Default: false

Silently ignored. Squash the resulting images layers into a single layer (As of version 1.xx)

labels
string

JSON map of key, value pairs to set as labels on the new image (As of version 1.xx)

networkmode
string
Default: "bridge"

Sets the networking mode for the run commands during build. Supported standard values are:

  • bridge limited to containers within a single host, port mapping required for external access
  • host no isolation between host and containers on this network
  • none disable all networking for this container
  • container: share networking with given container
  • --All other values are assumed to be a custom network's name (As of version 1.xx)
platform
string

Platform format os[/arch[/variant]] (As of version 1.xx)

target
string

Target build stage (As of version 1.xx)

outputs
string

output configuration TBD (As of version 1.xx)

httpproxy
boolean

Inject http proxy environment variables into container (As of version 2.0.0)

Responses

Response samples

Content type
application/json
{
  • "stream": "(build details...)\nSuccessfully built 8ba084515c724cbf90d447a63600c0a6\n"
}

Remove an image from the local storage.

Remove an image from the local storage.

path Parameters
name:.*
required
string

name or ID of image to remove

query Parameters
force
boolean

remove the image even if used by containers or has other tags

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Image exists

Check if image exists in local store

path Parameters
name:.*
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Export an image

Export an image

path Parameters
name:.*
required
string

the name or ID of the container

query Parameters
format
string

format for exported image

compress
boolean

use compression on image

Responses

Response samples

Content type
application/json
"string"

History of an image

Return parent layers of an image.

path Parameters
name:.*
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Comment": "string",
  • "Created": 0,
  • "CreatedBy": "string",
  • "Id": "string",
  • "Size": 0,
  • "Tags": [
    ]
}

Inspect an image

Obtain low-level information about an image

path Parameters
name:.*
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Annotations": {
    },
  • "Architecture": "string",
  • "Author": "string",
  • "Comment": "string",
  • "Config": {
    },
  • "Created": "2019-08-24T14:15:22Z",
  • "Digest": "string",
  • "GraphDriver": {
    },
  • "Healthcheck": {
    },
  • "History": [
    ],
  • "Id": "string",
  • "Labels": {
    },
  • "ManifestType": "string",
  • "NamesHistory": [
    ],
  • "Os": "string",
  • "Parent": "string",
  • "RepoDigests": [
    ],
  • "RepoTags": [
    ],
  • "RootFS": {
    },
  • "Size": 0,
  • "User": "string",
  • "Version": "string",
  • "VirtualSize": 0
}

Push Image

Push an image to a container registry

path Parameters
name:.*
required
string

Name of image to push.

query Parameters
destination
string

Allows for pushing the image to a different destination than the image refers to.

tlsVerify
boolean
Default: true

Require TLS verification.

header Parameters
X-Registry-Auth
string

A base64-encoded auth configuration.

Responses

Response samples

Content type
application/json
"string"

Tag an image

Tag an image so that it becomes part of a repository.

path Parameters
name:.*
required
string

the name or ID of the container

query Parameters
repo
string

the repository to tag in

tag
string

the name of the new tag

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Image tree

Retrieve the image tree for the provided image name or ID

path Parameters
name:.*
required
string

the name or ID of the container

query Parameters
whatrequires
boolean

show all child images and layers of the specified image

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "id": "string",
  • "layers": [
    ],
  • "size": "string",
  • "tags": [
    ]
}

Untag an image

Untag an image. If not repo and tag are specified, all tags are removed from the image.

path Parameters
name:.*
required
string

the name or ID of the container

query Parameters
repo
string

the repository to untag

tag
string

the name of the tag to untag

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Report on changes to images's filesystem; adds, deletes or modifications.

Returns which files in a images's filesystem have been added, deleted, or modified. The Kind of modification can be one of:

0: Modified 1: Added 2: Deleted

path Parameters
name
required
string

the name or id of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Export multiple images

Export multiple images into a single object. Only docker-archive is currently supported.

query Parameters
format
string

format for exported image (only docker-archive is supported)

references
Array of strings

references to images to export

compress
boolean

use compression on image

Responses

Response samples

Content type
application/json
"string"

Import image

Import a previously exported tarball as an image.

query Parameters
changes
Array of strings

Apply the following possible instructions to the created image: CMD | ENTRYPOINT | ENV | EXPOSE | LABEL | STOPSIGNAL | USER | VOLUME | WORKDIR. JSON encoded string

message
string

Set commit message for imported image

reference
string

Optional Name[:TAG] for the image

url
string

Load image from the specified URL

Request Body schema: application/x-www-form-urlencoded
upload
required
string <binary>

tarball for imported image

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Id": "string"
}

List Images

Returns a list of images on the server

query Parameters
all
boolean
Default: false

Show all images. Only images from a final layer (no children) are shown by default.

filters
string

A JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters:

  • before=(<image-name>[:<tag>], <image id> or <image@digest>)
  • dangling=true
  • label=key or label="key=value" of an image label
  • reference=(<image-name>[:<tag>])
  • id=(<image-id>)
  • since=(<image-name>[:<tag>], <image id> or <image@digest>)

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Load image

Load an image (oci-archive or docker-archive) stream.

Request Body schema: application/x-www-form-urlencoded
upload
required
string <binary>

tarball of container image

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Names": [
    ]
}

Prune unused images

Remove images that are not being used by a container

query Parameters
filters
string

filters to apply to image pruning, encoded as JSON (map[string][]string). Available filters:

  • dangling=<boolean> When set to true (or 1), prune only unused and untagged images. When set to false (or 0), all unused images are pruned.
  • until=<string> Prune images 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.
  • label (label=<key>, label=<key>=<value>, label!=<key>, or label!=<key>=<value>) Prune images with (or without, in case label!=... is used) the specified labels.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Pull images

Pull one or more images from a container registry.

query Parameters
reference
string

Mandatory reference to the image (e.g., quay.io/image/name:tag)

credentials
string

username:password for the registry

overrideArch
string

Pull image for the specified architecture.

overrideOS
string

Pull image for the specified operating system.

overrideVariant
string

Pull image for the specified variant.

tlsVerify
boolean
Default: true

Require TLS verification.

allTags
boolean

Pull all tagged images in the repository.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "error": "string",
  • "id": "string",
  • "images": [
    ],
  • "stream": "string"
}

Remove one or more images from the storage.

Remove one or more images from the storage.

query Parameters
images
Array of strings

Images IDs or names to remove.

all
boolean
Default: true

Remove all images.

force
boolean

Force image removal (including containers using the images).

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Deleted": [
    ],
  • "Errors": [
    ],
  • "ExitCode": 0,
  • "Untagged": [
    ]
}

Search images

Search registries for images

query Parameters
term
string

term to search

limit
integer

maximum number of results

noTrunc
boolean

do not truncate any of the result strings

filters
string

A JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters:

  • is-automated=(true|false)
  • is-official=(true|false)
  • stars=<number> Matches images that has at least 'number' stars.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Automated": "string",
  • "Description": "string",
  • "Index": "string",
  • "Name": "string",
  • "Official": "string",
  • "Stars": 0,
  • "Tag": "string"
}

manifests

Actions related to manifests

Remove

Remove an image from a manifest list

path Parameters
name:.*
required
string

the image associated with the manifest

query Parameters
digest
string

image digest to be removed

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

AddManifest

Add an image to a manifest list

path Parameters
name:.*
required
string

the name or ID of the manifest

Request Body schema:
application/json
application/json
application/x-tar

options for creating a manifest

all
boolean
object
arch
string
features
Array of strings
images
Array of strings
os
string
os_version
string
variant
string

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "all": true,
  • "annotation": {
    },
  • "arch": "string",
  • "features": [
    ],
  • "images": [
    ],
  • "os": "string",
  • "os_version": "string",
  • "variant": "string"
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Inspect

Display a manifest list

path Parameters
name:.*
required
string

the name or ID of the manifest

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Clone": { },
  • "Instances": [
    ],
  • "MIMEType": "string"
}

Push

Push a manifest list or image index to a registry

path Parameters
name
required
string

the name or ID of the manifest

query Parameters
destination
required
string

the destination for the manifest

all
boolean

push all images

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Create

Create a manifest list

query Parameters
name
required
string

manifest list name

image
string

name of the image

all
boolean

add all contents if given list

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

networks

Actions related to networks

Remove a network

Remove a CNI configured network

path Parameters
name
required
string

the name of the network

query Parameters
force
boolean

remove containers associated with network

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Err": "string",
  • "Name": "string"
}

Connect container to network

Connect a container to a network.

path Parameters
name
required
string

the name of the network

Request Body schema:
application/json
application/json
application/x-tar

attributes for connecting a container to a network

object

in:body

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "Body": {
    }
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Disconnect container from network

Disconnect a container from a network.

path Parameters
name
required
string

the name of the network

Request Body schema:
application/json
application/json
application/x-tar

attributes for disconnecting a container from a network

object

in:body

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "Body": {
    }
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Inspect a network

Display low level configuration for a CNI network

path Parameters
name
required
string

the name of the network

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Create network

Create a new CNI network configuration

query Parameters
name
string

optional name for new network

Request Body schema:
application/json
application/json
application/x-tar

attributes for creating a container

DisableDNS
boolean
Driver
string
Gateway
Array of integers <uint8> (An IP is a single IP address, a slice of bytes. Functions in this package accept either 4-byte (IPv4) or 16-byte (IPv6) slices as input.)

Note that in this documentation, referring to an IP address as an IPv4 address or an IPv6 address is a semantic property of the address, not just the length of the byte slice: a 16-byte slice can still be an IPv4 address.

IPv6
boolean
Internal
boolean
object
MacVLAN
string
object

Mapping of driver options and values.

object (An IPNet represents an IP network.)
object (An IPNet represents an IP network.)

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "DisableDNS": true,
  • "Driver": "string",
  • "Gateway": [
    ],
  • "IPv6": true,
  • "Internal": true,
  • "Labels": {
    },
  • "MacVLAN": "string",
  • "Options": {
    },
  • "Range": {
    },
  • "Subnet": {
    }
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Filename": "string"
}

List networks

Display summary of network configurations

query Parameters
filters
string

JSON encoded value of the filters (a map[string][]string) to process on the network list. Available filters:

  • name=[name] Matches network name (accepts regex).
  • id=[id] Matches for full or partial ID.
  • driver=[driver] Only bridge is supported.
  • label=[key] or label=[key=value] Matches networks based on the presence of a label alone or a label and a value.
  • plugin=[plugin] Matches CNI plugins included in a network (e.g bridge,portmap,firewall,tuning,dnsname,macvlan)

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

pods

Actions related to pods

Generate Systemd Units

Generate Systemd Units based on a pod or container.

path Parameters
name:.*
required
string

Name or ID of the container or pod.

query Parameters
useName
boolean
Default: false

Use container/pod names instead of IDs.

new
boolean
Default: false

Create a new container instead of starting an existing one.

time
integer
Default: 10

Stop timeout override.

restartPolicy
string
Default: "on-failure"
Enum: "no" "on-success" "on-failure" "on-abnormal" "on-watchdog" "on-abort" "always"

Systemd restart-policy.

containerPrefix
string
Default: "container"

Systemd unit name prefix for containers.

podPrefix
string
Default: "pod"

Systemd unit name prefix for pods.

separator
string
Default: "-"

Systemd unit name separator between name/id and prefix.

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Generate a Kubernetes YAML file.

Generate Kubernetes YAML based on a pod or container.

query Parameters
names
required
Array of strings

Name or ID of the container or pod.

service
boolean
Default: false

Generate YAML for a Kubernetes service object.

Responses

Response samples

Content type
application/json
"string"

Play a Kubernetes YAML file.

Create and run pods based on a Kubernetes YAML file (pod or service kind).

query Parameters
network
string

Connect the pod to this network.

tlsVerify
boolean
Default: true

Require HTTPS and verify signatures when contacting registries.

logDriver
string

Logging driver for the containers in the pod.

start
boolean
Default: true

Start the pod after creating it.

Request Body schema:
application/json
application/json
application/x-tar

Kubernetes YAML file.

string

Responses

Request samples

Content type
application/json
application/json
application/x-tar
"string"

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Pods": [
    ]
}

Remove pod

path Parameters
name
required
string

the name or ID of the pod

query Parameters
force
boolean

force removal of a running pod by first stopping all containers, then removing all containers in the pod

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Err": "string",
  • "Id": "string"
}

Pod exists

Check if a pod exists by name or ID

path Parameters
name
required
string

the name or ID of the pod

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Inspect pod

path Parameters
name
required
string

the name or ID of the pod

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "CgroupParent": "string",
  • "CgroupPath": "string",
  • "Containers": [
    ],
  • "CreateCgroup": true,
  • "CreateCommand": [
    ],
  • "CreateInfra": true,
  • "Created": "2019-08-24T14:15:22Z",
  • "Hostname": "string",
  • "Id": "string",
  • "InfraConfig": {
    },
  • "InfraContainerID": "string",
  • "Labels": {
    },
  • "Name": "string",
  • "Namespace": "string",
  • "NumContainers": 0,
  • "SharedNamespaces": [
    ],
  • "State": "string"
}

Kill a pod

path Parameters
name
required
string

the name or ID of the pod

query Parameters
signal
string
Default: "SIGKILL"

signal to be sent to pod

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Errs": [
    ],
  • "Id": "string"
}

Pause a pod

Pause a pod

path Parameters
name
required
string

the name or ID of the pod

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Errs": [
    ],
  • "Id": "string"
}

Restart a pod

path Parameters
name
required
string

the name or ID of the pod

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Errs": [
    ],
  • "Id": "string"
}

Start a pod

path Parameters
name
required
string

the name or ID of the pod

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Errs": [
    ],
  • "Id": "string"
}

Stop a pod

path Parameters
name
required
string

the name or ID of the pod

query Parameters
t
integer

timeout

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Errs": [
    ],
  • "Id": "string"
}

List processes

List processes running inside a pod

path Parameters
name
required
string

Name of pod to query for processes

query Parameters
stream
boolean
Default: true

Stream the output

ps_args
string
Default: "-ef"

arguments to pass to ps such as aux. Requires ps(1) to be installed in the container if no ps(1) compatible AIX descriptors are used.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Processes": [
    ],
  • "Titles": [
    ]
}

Unpause a pod

path Parameters
name
required
string

the name or ID of the pod

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Errs": [
    ],
  • "Id": "string"
}

Create a pod

Request Body schema:
application/json
application/json
application/x-tar

attributes for creating a pod

cgroup_parent
string

CgroupParent is the parent for the CGroup that the pod will create. This pod cgroup will, in turn, be the default cgroup parent for all containers in the pod. Optional.

cni_networks
Array of strings

CNINetworks is a list of CNI networks that the infra container will join. As, by default, containers share their network with the infra container, these networks will effectively be joined by the entire pod. Only available when NetNS is set to Bridge, the default for root. Optional.

dns_option
Array of strings

DNSOption is a set of DNS options that will be used in the infra container's resolv.conf, which will, by default, be shared with all containers in the pod. Conflicts with NoInfra=true. Optional.

dns_search
Array of strings

DNSSearch is a set of DNS search domains that will be used in the infra container's resolv.conf, which will, by default, be shared with all containers in the pod. If not provided, DNS search domains from the host's resolv.conf will be used. Conflicts with NoInfra=true. Optional.

dns_server
Array of Array of integers (An IP is a single IP address, a slice of bytes. Functions in this package accept either 4-byte (IPv4) or 16-byte (IPv6) slices as input.)

DNSServer is a set of DNS servers that will be used in the infra container's resolv.conf, which will, by default, be shared with all containers in the pod. If not provided, the host's DNS servers will be used, unless the only server set is a localhost address. As the container cannot connect to the host's localhost, a default server will instead be set. Conflicts with NoInfra=true. Optional.

hostadd
Array of strings

HostAdd is a set of hosts that will be added to the infra container's etc/hosts that will, by default, be shared with all containers in the pod. Conflicts with NoInfra=true and NoManageHosts. Optional.

hostname
string

Hostname is the pod's hostname. If not set, the name of the pod will be used (if a name was not provided here, the name auto-generated for the pod will be used). This will be used by the infra container and all containers in the pod as long as the UTS namespace is shared. Optional.

infra_command
Array of strings

InfraCommand sets the command that will be used to start the infra container. If not set, the default set in the Libpod configuration file will be used. Conflicts with NoInfra=true. Optional.

infra_conmon_pid_file
string

InfraConmonPidFile is a custom path to store the infra container's conmon PID.

infra_image
string

InfraImage is the image that will be used for the infra container. If not set, the default set in the Libpod configuration file will be used. Conflicts with NoInfra=true. Optional.

object

Labels are key-value pairs that are used to add metadata to pods. Optional.

name
string

Name is the name of the pod. If not provided, a name will be generated when the pod is created. Optional.

object (Namespace)

Namespace describes the namespace

object

NetworkOptions are additional options for each network Optional.

no_infra
boolean

NoInfra tells the pod not to create an infra container. If this is done, many networking-related options will become unavailable. Conflicts with setting any options in PodNetworkConfig, and the InfraCommand and InfraImages in this struct. Optional.

no_manage_hosts
boolean

NoManageHosts indicates that /etc/hosts should not be managed by the pod. Instead, each container will create a separate /etc/hosts as they would if not in a pod. Conflicts with HostAdd.

no_manage_resolv_conf
boolean

NoManageResolvConf indicates that /etc/resolv.conf should not be managed by the pod. Instead, each container will create and manage a separate resolv.conf as if they had not joined a pod. Conflicts with NoInfra=true and DNSServer, DNSSearch, DNSOption. Optional.

pod_create_command
Array of strings

PodCreateCommand is the command used to create this pod. This will be shown in the output of Inspect() on the pod, and may also be used by some tools that wish to recreate the pod (e.g. podman generate systemd --new). Optional.

Array of objects (PortMapping is one or more ports that will be mapped into the container.)

PortMappings is a set of ports to map into the infra container. As, by default, containers share their network with the infra container, this will forward the ports to the entire pod. Only available if NetNS is set to Bridge or Slirp. Optional.

shared_namespaces
Array of strings

SharedNamespaces instructs the pod to share a set of namespaces. Shared namespaces will be joined (by default) by every container which joins the pod. If not set and NoInfra is false, the pod will set a default set of namespaces to share. Conflicts with NoInfra=true. Optional.

static_ip
Array of integers <uint8> (An IP is a single IP address, a slice of bytes. Functions in this package accept either 4-byte (IPv4) or 16-byte (IPv6) slices as input.)

Note that in this documentation, referring to an IP address as an IPv4 address or an IPv6 address is a semantic property of the address, not just the length of the byte slice: a 16-byte slice can still be an IPv4 address.

static_mac
Array of integers <uint8> (A HardwareAddr represents a physical hardware address.)

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "cgroup_parent": "string",
  • "cni_networks": [
    ],
  • "dns_option": [
    ],
  • "dns_search": [
    ],
  • "dns_server": [
    ],
  • "hostadd": [
    ],
  • "hostname": "string",
  • "infra_command": [
    ],
  • "infra_conmon_pid_file": "string",
  • "infra_image": "string",
  • "labels": {
    },
  • "name": "string",
  • "netns": {
    },
  • "network_options": {
    },
  • "no_infra": true,
  • "no_manage_hosts": true,
  • "no_manage_resolv_conf": true,
  • "pod_create_command": [
    ],
  • "portmappings": [
    ],
  • "shared_namespaces": [
    ],
  • "static_ip": [
    ],
  • "static_mac": [
    ]
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

List pods

query Parameters
filters
string

needs description and plumbing for filters

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Prune unused pods

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Err": "string",
  • "Id": "string"
}

Get stats for one or more pods

Display a live stream of resource usage statistics for the containers in one or more pods

query Parameters
all
boolean

Provide statistics for all running pods.

namesOrIDs
Array of strings

Names or IDs of pods.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Processes": [
    ],
  • "Titles": [
    ]
}

volumes

Actions related to volumes

Remove volume

path Parameters
name
required
string

the name or ID of the volume

query Parameters
force
boolean

force removal

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Inspect volume

path Parameters
name
required
string

the name or ID of the volume

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Anonymous": true,
  • "CreatedAt": "2019-08-24T14:15:22Z",
  • "Driver": "string",
  • "GID": 0,
  • "Labels": {
    },
  • "Mountpoint": "string",
  • "Name": "string",
  • "Options": {
    },
  • "Scope": "string",
  • "Status": {
    },
  • "UID": 0
}

Create a volume

Request Body schema:
application/json
application/json
application/x-tar

attributes for creating a container

Driver
string

Volume driver to use

object

User-defined key/value metadata.

Name
string

New volume's name. Can be left blank

object

Mapping of driver options and values.

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "Driver": "string",
  • "Label": {
    },
  • "Name": "string",
  • "Options": {
    }
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Anonymous": true,
  • "CreatedAt": "2019-08-24T14:15:22Z",
  • "Driver": "string",
  • "GID": 0,
  • "Labels": {
    },
  • "Mountpoint": "string",
  • "Name": "string",
  • "Options": {
    },
  • "Scope": "string",
  • "Status": {
    },
  • "UID": 0
}

List volumes

Returns a list of volumes

query Parameters
filters
string

JSON encoded value of the filters (a map[string][]string) to process on the volumes list. Available filters:

  • driver= Matches volumes based on their driver.
  • label= or label=: Matches volumes based on the presence of a label alone or a label and a value.
  • name= Matches all of volume name.
  • opt= Matches a storage driver options

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Prune volumes

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

system

Actions related to Podman engine

Ping service

Return protocol information in response headers. HEAD /libpod/_ping is also supported. /_ping is available for compatibility with other engines. The '_ping' endpoints are not versioned.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Get events

Returns events filtered on query parameters

query Parameters
since
string

start streaming events from this time

until
string

stop streaming events later than this

filters
string

JSON encoded map[string][]string of constraints

stream
boolean
Default: true

when false, do not follow events

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Get info

Returns information on the system and libpod configuration

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "host": {
    },
  • "registries": {
    },
  • "store": {
    },
  • "version": {
    }
}

Show disk usage

Return information about disk usage for containers, images, and volumes

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Containers": [
    ],
  • "Images": [
    ],
  • "Volumes": [
    ]
}

Prune unused data

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "ContainerPruneReports": [
    ],
  • "ImagePruneReports": [
    ],
  • "PodPruneReport": [
    ],
  • "ReclaimedSpace": 0,
  • "VolumePruneReports": [
    ]
}

Component Version information

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Client": {
    },
  • "Server": {
    }
}

containers (compat)

Actions related to containers for the compatibility endpoints

New Image

Create a new image from a container

query Parameters
container
string

the name or ID of a container

repo
string

the repository name for the created image

tag
string

tag name for the created image

comment
string

commit message

author
string

author of the image

pause
boolean

pause the container before committing it

changes
string

instructions to apply while committing in Dockerfile format

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Remove a container

path Parameters
name
required
string

the name or ID of the container

query Parameters
force
boolean
Default: false

If the container is running, kill it before removing it.

v
boolean
Default: false

Remove the volumes associated with the container.

link
boolean

not supported

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Get files from a container

Get a tar archive of files from a container

path Parameters
name
required
string

container name or id

query Parameters
path
required
string

Path to a directory in the container to extract

Responses

Response samples

Content type
application/json
"string"

Put files into a container

Put a tar archive of files into a container

path Parameters
name
required
string

container name or id

query Parameters
path
required
string

Path to a directory in the container to extract

noOverwriteDirNonDir
string

if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa (1 or true)

copyUIDGID
string

copy UID/GID maps to the dest file or di (1 or true)

Request Body schema:
application/json
application/json
application/x-tar

tarfile of files to copy into the container

string

Responses

Request samples

Content type
application/json
application/json
application/x-tar
"string"

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Attach to a container

Hijacks the connection to forward the container's standard streams to the client.

path Parameters
name
required
string

the name or ID of the container

query Parameters
detachKeys
string

keys to use for detaching from the container

logs
boolean

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

stream
boolean
Default: true

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

stdout
boolean

Attach to container STDOUT

stderr
boolean

Attach to container STDERR

stdin
boolean

Attach to container STDIN

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Export a container

Export the contents of a container as a tarball.

path Parameters
name
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Inspect container

Return low-level information about a container.

path Parameters
name
required
string

the name or id of the container

query Parameters
size
boolean
Default: false

include the size of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "AppArmorProfile": "string",
  • "Args": [
    ],
  • "Config": {
    },
  • "Created": "string",
  • "Driver": "string",
  • "ExecIDs": [
    ],
  • "GraphDriver": {
    },
  • "HostConfig": {
    },
  • "HostnamePath": "string",
  • "HostsPath": "string",
  • "Id": "string",
  • "Image": "string",
  • "LogPath": "string",
  • "MountLabel": "string",
  • "Mounts": [
    ],
  • "Name": "string",
  • "NetworkSettings": {
    },
  • "Node": {
    },
  • "Path": "string",
  • "Platform": "string",
  • "ProcessLabel": "string",
  • "ResolvConfPath": "string",
  • "RestartCount": 0,
  • "SizeRootFs": 0,
  • "SizeRw": 0,
  • "State": {
    }
}

Kill container

Signal to send to the container as an integer or string (e.g. SIGINT)

path Parameters
name
required
string

the name or ID of the container

query Parameters
signal
string
Default: "SIGKILL"

signal to be sent to container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Get container logs

Get stdout and stderr logs from a container.

path Parameters
name
required
string

the name or ID of the container

query Parameters
follow
boolean

Keep connection after returning logs.

stdout
boolean

Return logs from stdout

stderr
boolean

Return logs from stderr

since
string

Only return logs since this time, as a UNIX timestamp

until
string

Only return logs before this time, as a UNIX timestamp

timestamps
boolean
Default: false

Add timestamps to every log line

tail
string
Default: "all"

Only return this number of log lines from the end of the logs

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Pause container

Use the cgroups freezer to suspend all processes in a container.

path Parameters
name
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Rename an existing container

Change the name of an existing container.

path Parameters
name
required
string

Full or partial ID or full name of the container to rename

query Parameters
name
required
string

New name for the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Resize a container's TTY

Resize the terminal attached to a container (for use with Attach).

path Parameters
name
required
string

the name or ID of the container

query Parameters
h
integer

Height to set for the terminal, in characters

w
integer

Width to set for the terminal, in characters

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{ }

Restart container

path Parameters
name
required
string

the name or ID of the container

query Parameters
t
integer

timeout before sending kill signal to container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Start a container

path Parameters
name
required
string

the name or ID of the container

query Parameters
detachKeys
string
Default: "ctrl-p,ctrl-q"

Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl- where is one of: a-z, @, ^, [, , or _.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Get stats for a container

This returns a live stream of a container’s resource usage statistics.

path Parameters
name
required
string

the name or ID of the container

query Parameters
stream
boolean
Default: true

Stream the output

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Stop a container

Stop a container

path Parameters
name
required
string

the name or ID of the container

query Parameters
t
integer

number of seconds to wait before killing container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

List processes running inside a container

path Parameters
name
required
string

the name or ID of the container

query Parameters
ps_args
string

arguments to pass to ps such as aux. Requires ps(1) to be installed in the container if no ps(1) compatible AIX descriptors are used.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Processes": [
    ],
  • "Titles": [
    ]
}

Unpause container

Resume a paused container

path Parameters
name
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Wait on a container

Block until a container stops or given condition is met.

path Parameters
name
required
string

the name or ID of the container

query Parameters
condition
string

wait until container is to a given condition. default is stopped. valid conditions are:

  • configured
  • created
  • exited
  • paused
  • running
  • stopped

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Error": {
    },
  • "StatusCode": 0
}

Create a container

query Parameters
name
string

container name

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Id": "string",
  • "Warnings": [
    ]
}

List containers

Returns a list of containers

query Parameters
all
boolean
Default: false

Return all containers. By default, only running containers are shown

limit
integer

Return this number of most recently created containers, including non-running ones.

size
boolean
Default: false

Return the size of container as fields SizeRw and SizeRootFs.

filters
string

Returns a list of containers.

  • ancestor=([:], , or <image@digest>)
  • before=( or )
  • expose=([/]|/[])
  • exited= containers with exit code of
  • health=(starting|healthy|unhealthy|none)
  • id= a container's ID
  • is-task=(true|false)
  • label=key or label="key=value" of a container label
  • name= a container's name
  • network=( or )
  • publish=([/]|/[])
  • since=( or )
  • status=(created|restarting|running|removing|paused|exited|dead)
  • volume=( or )

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{ }

Delete stopped containers

Remove containers not in use

query Parameters
filters
string

Filters to process on the prune list, encoded as JSON (a map[string][]string). Available filters:

  • 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.
  • 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.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Copy files from a container

Copy a tar archive of files from a container

path Parameters
name
required
string

container name or id

query Parameters
path
required
string

Path to a directory in the container to extract

Responses

Response samples

Content type
application/json
"string"

Report on changes to container's filesystem; adds, deletes or modifications.

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

path Parameters
name
required
string

the name or id of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

exec (compat)

Actions related to exec for the compatibility endpoints

Create an exec instance

Create an exec session to run a command inside a running container. Exec sessions will be automatically removed 5 minutes after they exit.

path Parameters
name
required
string

name of container

Request Body schema:
application/json
application/json
application/x-tar

Attributes for create

AttachStderr
boolean

Attach to stderr of the exec command

AttachStdin
boolean

Attach to stdin of the exec command

AttachStdout
boolean

Attach to stdout of the exec command

Cmd
Array of strings

Command to run, as a string or array of strings.

DetachKeys
string

"Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl- where is one of: a-z, @, ^, [, , or _."

Env
Array of strings

A list of environment variables in the form ["VAR=value", ...]

Privileged
boolean
Default: false

Runs the exec process with extended privileges

Tty
boolean

Allocate a pseudo-TTY

User
string

"The user, and optionally, group to run the exec process inside the container. Format is one of: user, user:group, uid, or uid:gid."

WorkingDir
string

The working directory for the exec process inside the container.

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "AttachStderr": true,
  • "AttachStdin": true,
  • "AttachStdout": true,
  • "Cmd": [
    ],
  • "DetachKeys": "string",
  • "Env": [
    ],
  • "Privileged": false,
  • "Tty": true,
  • "User": "string",
  • "WorkingDir": "string"
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Inspect an exec instance

Return low-level information about an exec instance.

path Parameters
id
required
string

Exec instance ID

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if tty was specified as part of creating and starting the exec instance.

path Parameters
id
required
string

Exec instance ID

query Parameters
h
integer

Height of the TTY session in characters

w
integer

Width of the TTY session in characters

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

path Parameters
id
required
string

Exec instance ID

Request Body schema:
application/json
application/json
application/x-tar

Attributes for start

Detach
boolean

Detach from the command. Not presently supported.

Tty
boolean

Allocate a pseudo-TTY. Presently ignored.

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "Detach": true,
  • "Tty": true
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

images (compat)

Actions related to images for the compatibility endpoints

Create image

Build an image from the given Dockerfile(s)

query Parameters
dockerfile
string
Default: "Dockerfile"

Path within the build context to the Dockerfile. This is ignored if remote is specified and points to an external Dockerfile.

t
string
Default: "latest"

A name and optional tag to apply to the image in the name:tag format. If you omit the tag the default latest value is assumed. You can provide several t parameters.

extrahosts
string

TBD Extra hosts to add to /etc/hosts (As of version 1.xx)

remote
string

A Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called Dockerfile and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the dockerfile parameter is also specified, there must be a file with the corresponding path inside the tarball. (As of version 1.xx)

q
boolean
Default: false

Suppress verbose build output

nocache
boolean
Default: false

Do not use the cache when building the image (As of version 1.xx)

cachefrom
string

JSON array of images used to build cache resolution (As of version 1.xx)

pull
boolean
Default: false

Attempt to pull the image even if an older image exists locally (As of version 1.xx)

rm
boolean
Default: true

Remove intermediate containers after a successful build (As of version 1.xx)

forcerm
boolean
Default: false

Always remove intermediate containers, even upon failure (As of version 1.xx)

memory
integer

Memory is the upper limit (in bytes) on how much memory running containers can use (As of version 1.xx)

memswap
integer

MemorySwap limits the amount of memory and swap together (As of version 1.xx)

cpushares
integer

CPUShares (relative weight (As of version 1.xx)

cpusetcpus
string

CPUSetCPUs in which to allow execution (0-3, 0,1) (As of version 1.xx)

cpuperiod
integer

CPUPeriod limits the CPU CFS (Completely Fair Scheduler) period (As of version 1.xx)

cpuquota
integer

CPUQuota limits the CPU CFS (Completely Fair Scheduler) quota (As of version 1.xx)

buildargs
string

JSON map of string pairs denoting build-time variables. For example, the build argument Foo with the value of bar would be encoded in JSON as ["Foo":"bar"].

For example, buildargs={"Foo":"bar"}.

Note(s):

  • This should not be used to pass secrets.
  • The value of buildargs should be URI component encoded before being passed to the API.

(As of version 1.xx)

shmsize
integer
Default: 67108864

ShmSize is the "size" value to use when mounting an shmfs on the container's /dev/shm directory. Default is 64MB (As of version 1.xx)

squash
boolean
Default: false

Silently ignored. Squash the resulting images layers into a single layer (As of version 1.xx)

labels
string

JSON map of key, value pairs to set as labels on the new image (As of version 1.xx)

networkmode
string
Default: "bridge"

Sets the networking mode for the run commands during build. Supported standard values are:

  • bridge limited to containers within a single host, port mapping required for external access
  • host no isolation between host and containers on this network
  • none disable all networking for this container
  • container: share networking with given container
  • --All other values are assumed to be a custom network's name (As of version 1.xx)
platform
string

Platform format os[/arch[/variant]] (As of version 1.xx)

target
string

Target build stage (As of version 1.xx)

outputs
string

output configuration TBD (As of version 1.xx)

Responses

Response samples

Content type
application/json
{
  • "stream": "(build details...)\nSuccessfully built 8ba084515c724cbf90d447a63600c0a6\n"
}

Remove Image

Delete an image from local storage

path Parameters
name:.*
required
string

name or ID of image to delete

query Parameters
force
boolean

remove the image even if used by containers or has other tags

noprune
boolean

not supported. will be logged as an invalid parameter if enabled

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Export an image

Export an image in tarball format

path Parameters
name:.*
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
"string"

History of an image

Return parent layers of an image.

path Parameters
name:.*
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Comment": "string",
  • "Created": 0,
  • "CreatedBy": "string",
  • "Id": "string",
  • "Size": 0,
  • "Tags": [
    ]
}

Inspect an image

Return low-level information about an image.

path Parameters
name:.*
required
string

the name or ID of the container

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Architecture": "string",
  • "Author": "string",
  • "Comment": "string",
  • "Config": {
    },
  • "Container": "string",
  • "ContainerConfig": {
    },
  • "Created": "string",
  • "DockerVersion": "string",
  • "GraphDriver": {
    },
  • "Id": "string",
  • "Metadata": {
    },
  • "Os": "string",
  • "OsVersion": "string",
  • "Parent": "string",
  • "RepoDigests": [
    ],
  • "RepoTags": [
    ],
  • "RootFS": {
    },
  • "Size": 0,
  • "Variant": "string",
  • "VirtualSize": 0
}

Push Image

Push an image to a container registry

path Parameters
name:.*
required
string

Name of image to push.

query Parameters
tag
string

The tag to associate with the image on the registry.

header Parameters
X-Registry-Auth
string

A base64-encoded auth configuration.

Responses

Response samples

Content type
application/json
"string"

Tag an image

Tag an image so that it becomes part of a repository.

path Parameters
name:.*
required
string

the name or ID of the container

query Parameters
repo
string

the repository to tag in

tag
string

the name of the new tag

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Create an image

Create an image by either pulling it from a registry or importing it.

query Parameters
fromImage
string

needs description

fromSrc
string

needs description

tag
string

needs description

header Parameters
X-Registry-Auth
string

A base64-encoded auth configuration.

Request Body schema:
application/json
application/json
application/x-tar

Image content if fromSrc parameter was used

string

Responses

Request samples

Content type
application/json
application/json
application/x-tar
"string"

Response samples

Content type
application/json
application/json
text/plain
text/html
{ }

Export several images

Get a tarball containing all images and metadata for several image repositories

query Parameters
names
required
string

one or more image names or IDs comma separated

Responses

Response samples

Content type
application/json
"string"

List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

query Parameters
all
boolean
Default: false

Show all images. Only images from a final layer (no children) are shown by default.

filters
string

A JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters:

  • before=(<image-name>[:<tag>], <image id> or <image@digest>)
  • dangling=true
  • label=key or label="key=value" of an image label
  • reference=(<image-name>[:<tag>])
  • since=(<image-name>[:<tag>], <image id> or <image@digest>)
digests
boolean
Default: false

Not supported

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Import image

Load a set of images and tags into a repository.

query Parameters
quiet
boolean

not supported

Request Body schema:
application/json
application/json
application/x-tar

tarball of container image

string

Responses

Request samples

Content type
application/json
application/json
application/x-tar
"string"

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Prune unused images

Remove images from local storage that are not being used by a container

query Parameters
filters
string

filters to apply to image pruning, encoded as JSON (map[string][]string). Available filters:

  • dangling=<boolean> When set to true (or 1), prune only unused and untagged images. When set to false (or 0), all unused images are pruned.
  • until=<string> Prune images 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.
  • label (label=<key>, label=<key>=<value>, label!=<key>, or label!=<key>=<value>) Prune images with (or without, in case label!=... is used) the specified labels.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Search images

Search registries for an image

query Parameters
term
string

term to search

limit
integer

maximum number of results

filters
string

A JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters:

  • is-automated=(true|false)
  • is-official=(true|false)
  • stars=<number> Matches images that has at least 'number' stars.
listTags
boolean

list the available tags in the repository

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Automated": "string",
  • "Description": "string",
  • "Index": "string",
  • "Name": "string",
  • "Official": "string",
  • "Stars": 0,
  • "Tag": "string"
}

networks (compat)

Actions related to compatibility networks

List networks

Display summary of network configurations

query Parameters
filters
string

JSON encoded value of the filters (a map[string][]string) to process on the network list. Currently available filters:

  • name=[name] Matches network name (accepts regex).
  • id=[id] Matches for full or partial ID.
  • driver=[driver] Only bridge is supported.
  • label=[key] or label=[key=value] Matches networks based on the presence of a label alone or a label and a value.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
[
  • {
    }
]

Remove a network

Remove a network

path Parameters
name
required
string

the name of the network

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Inspect a network

Display low level configuration network

path Parameters
name
required
string

the name of the network

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Attachable": true,
  • "ConfigFrom": {
    },
  • "ConfigOnly": true,
  • "Containers": {
    },
  • "Created": "2019-08-24T14:15:22Z",
  • "Driver": "string",
  • "EnableIPv6": true,
  • "IPAM": {
    },
  • "Id": "string",
  • "Ingress": true,
  • "Internal": true,
  • "Labels": {
    },
  • "Name": "string",
  • "Options": {
    },
  • "Peers": [
    ],
  • "Scope": "string",
  • "Services": {
    }
}

Connect container to network

Connect a container to a network. This endpoint is current a no-op

path Parameters
name
required
string

the name of the network

Request Body schema:
application/json
application/json
application/x-tar

attributes for connecting a container to a network

object

in:body

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "Body": {
    }
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Disconnect container from network

Disconnect a container from a network. This endpoint is current a no-op

path Parameters
name
required
string

the name of the network

Request Body schema:
application/json
application/json
application/x-tar

attributes for disconnecting a container from a network

object

in:body

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "Body": {
    }
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Create network

Create a network configuration

Request Body schema:
application/json
application/json
application/x-tar

attributes for creating a container

Attachable
boolean
CheckDuplicate
boolean

Check for networks with duplicate names. Network is primarily keyed based on a random ID and not on the name. Network name is strictly a user-friendly alias to the network which is uniquely identified using ID. And there is no guaranteed way to check for duplicates. Option CheckDuplicate is there to provide a best effort checking of any networks which has the same name but it is not guaranteed to catch all name collisions.

object (ConfigReference)

ConfigReference specifies the source which provides a network's configuration

ConfigOnly
boolean
Driver
string
EnableIPv6
boolean
object (IPAM)

IPAM represents IP Address Management

Ingress
boolean
Internal
boolean
object
Name
string
object
Scope
string

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "Attachable": true,
  • "CheckDuplicate": true,
  • "ConfigFrom": {
    },
  • "ConfigOnly": true,
  • "Driver": "string",
  • "EnableIPv6": true,
  • "IPAM": {
    },
  • "Ingress": true,
  • "Internal": true,
  • "Labels": {
    },
  • "Name": "string",
  • "Options": {
    },
  • "Scope": "string"
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Attachable": true,
  • "CheckDuplicate": true,
  • "ConfigFrom": {
    },
  • "ConfigOnly": true,
  • "Driver": "string",
  • "EnableIPv6": true,
  • "IPAM": {
    },
  • "Ingress": true,
  • "Internal": true,
  • "Labels": {
    },
  • "Options": {
    },
  • "Scope": "string"
}

Delete unused networks

Not supported

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

volumes (compat)

Actions related to volumes for the compatibility endpoints

List volumes

Returns a list of volume

query Parameters
filters
string

JSON encoded value of the filters (a map[string][]string) to process on the volumes list. Available filters:

  • driver= Matches volumes based on their driver.
  • label= or label=: Matches volumes based on the presence of a label alone or a label and a value.
  • name= Matches all of volume name.

Note: The boolean dangling filter is not yet implemented for this endpoint.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Volumes": [
    ]
}

Remove volume

path Parameters
name
required
string

the name or ID of the volume

query Parameters
force
boolean

Force removal of the volume. This actually only causes errors due to the names volume not being found to be suppressed, which is the behaviour Docker implements.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Inspect volume

path Parameters
name
required
string

the name or ID of the volume

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "CreatedAt": "string",
  • "Driver": "string",
  • "Labels": {
    },
  • "Mountpoint": "string",
  • "Name": "string",
  • "Options": {
    },
  • "Scope": "string",
  • "Status": {
    },
  • "UsageData": {
    }
}

Create a volume

Request Body schema:
application/json
application/json
application/x-tar

attributes for creating a container. Note: If a volume by the same name exists, a 201 response with that volume's information will be generated.

Driver
required
string

Name of the volume driver to use.

required
object

A mapping of driver options and values. These options are passed directly to the driver and are driver specific.

required
object

User-defined key/value metadata.

Name
required
string

The new volume's name. If not specified, Docker generates a name.

Responses

Request samples

Content type
application/json
application/json
application/x-tar
{
  • "Driver": "string",
  • "DriverOpts": {
    },
  • "Labels": {
    },
  • "Name": "string"
}

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "CreatedAt": "string",
  • "Driver": "string",
  • "Labels": {
    },
  • "Mountpoint": "string",
  • "Name": "string",
  • "Options": {
    },
  • "Scope": "string",
  • "Status": {
    },
  • "UsageData": {
    }
}

Prune volumes

query Parameters
filters
string

JSON encoded value of filters (a map[string][]string) to match volumes against before pruning.

Note: No filters are currently supported and any filters specified will cause an error response.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "SpaceReclaimed": 0,
  • "VolumesDeleted": [
    ]
}

system (compat)

Actions related to Podman and compatibility engines

Get events

Returns events filtered on query parameters

query Parameters
since
string

start streaming events from this time

until
string

stop streaming events later than this

filters
string

JSON encoded map[string][]string of constraints

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Get info

Returns information on the system and libpod configuration

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Ping service

Return protocol information in response headers. HEAD /libpod/_ping is also supported. /_ping is available for compatibility with other engines. The '_ping' endpoints are not versioned.

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "cause": "API root cause",
  • "message": "human error message",
  • "response": 0
}

Component Version information

Responses

Response samples

Content type
application/json
application/json
text/plain
text/html
{
  • "Client": {
    },
  • "Server": {
    }
}