Podman containers (compat) API

openapi: 3.2.0
info:
  contact:
    email: podman@lists.podman.io
    name: Podman
    url: https://podman.io/community/
  description: 'This documentation describes the Podman v2.x+ RESTful API. It consists of a Docker-compatible

    API and a Libpod API providing support for Podman’s unique features such as pods.


    To start the service and keep it running for 5,000 seconds (-t 0 runs forever):


    podman system service -t 5000 &


    You can then use cURL on the socket using requests documented below.


    NOTE: if you install the package podman-docker, it will create a symbolic

    link for /run/docker.sock to /run/podman/podman.sock


    NOTE: Some fields in the API response JSON are encoded as omitempty, which means that

    if said field has a zero value, they will not be encoded in the API response. This

    is a feature to help reduce the size of the JSON responses returned via the API.


    NOTE: Due to the limitations of [go-swagger](https://github.com/go-swagger/go-swagger),

    some field values that have a complex type show up as null in the docs as well as in the

    API responses. This is because the zero value for the field type is null. The field

    description in the docs will state what type the field is expected to be for such cases.


    See podman-system-service(1) for more information.


    Quick Examples:


    ''podman info''


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


    ''podman pull quay.io/containers/podman''


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


    ''podman list images''


    curl --unix-socket /run/podman/podman.sock -v ''http://d/v6.0.0/libpod/images/json'' | jq'
  license:
    name: Apache-2.0
    url: https://opensource.org/licenses/Apache-2.0
  termsOfService: https://github.com/containers/podman/blob/913caaa9b1de2b63692c9bae15120208194c9eb3/LICENSE
  title: supports a RESTful API for the Libpod library artifacts containers (compat) containers (compat) API
  version: 5.0.0
  x-logo:
  - url: https://raw.githubusercontent.com/containers/libpod/main/logo/podman-logo.png
  - altText: Podman logo
servers:
- url: http://podman.io/
- url: https://podman.io/
tags:
- description: Actions related to containers for the compatibility endpoints
  name: containers (compat)
paths:
  /commit:
    post:
      description: Create a new image from a container
      operationId: ImageCommit
      parameters:
      - description: the name or ID of a container
        in: query
        name: container
        schema:
          type: string
      - description: the repository name for the created image
        in: query
        name: repo
        schema:
          type: string
      - description: tag name for the created image
        in: query
        name: tag
        schema:
          type: string
      - description: commit message
        in: query
        name: comment
        schema:
          type: string
      - description: author of the image
        in: query
        name: author
        schema:
          type: string
      - description: pause the container before committing it
        in: query
        name: pause
        schema:
          type: boolean
      - description: instructions to apply while committing in Dockerfile format
        in: query
        name: changes
        schema:
          type: string
      - description: squash newly built layers into a single new layer
        in: query
        name: squash
        schema:
          type: boolean
      responses:
        '201':
          description: no error
        '404':
          $ref: '#/components/responses/imageNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: New Image
      tags:
      - containers (compat)
  /containers/{name}:
    delete:
      operationId: ContainerDelete
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: If the container is running, kill it before removing it.
        in: query
        name: force
        schema:
          type: boolean
          default: false
      - description: Remove the volumes associated with the container.
        in: query
        name: v
        schema:
          type: boolean
          default: false
      - description: not supported
        in: query
        name: link
        schema:
          type: boolean
      - description: Ignore if a specified container does not exist.
        in: query
        name: ignore
        schema:
          type: boolean
          default: false
      - description: Remove container dependencies.
        in: query
        name: depend
        schema:
          type: boolean
          default: false
      - description: Number of seconds to wait before forcibly stopping the container.
        in: query
        name: timeout
        schema:
          type: integer
      - description: Remove anonymous volumes associated with the container.
        in: query
        name: volumes
        schema:
          type: boolean
          default: false
      responses:
        '204':
          description: no error
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Remove a container
      tags:
      - containers (compat)
  /containers/{name}/archive:
    get:
      description: Get a tar archive of files from a container
      operationId: ContainerArchive
      parameters:
      - description: container name or id
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Path to a directory in the container to extract
        in: query
        name: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: no error
          content:
            application/json:
              schema:
                format: binary
                type: string
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Get files from a container
      tags:
      - containers (compat)
    put:
      description: Put a tar archive of files into a container
      operationId: PutContainerArchive
      parameters:
      - description: container name or id
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Path to a directory in the container to extract
        in: query
        name: path
        required: true
        schema:
          type: string
      - description: if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa (1 or true)
        in: query
        name: noOverwriteDirNonDir
        schema:
          type: string
      - description: copy UID/GID maps to the dest file or di (1 or true)
        in: query
        name: copyUIDGID
        schema:
          type: string
      responses:
        '200':
          description: no error
        '400':
          $ref: '#/components/responses/badParamError'
        '403':
          description: the container rootfs is read-only
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Put files into a container
      tags:
      - containers (compat)
      requestBody:
        content:
          application/json:
            schema:
              type: string
          application/x-tar:
            schema:
              type: string
        description: tarfile of files to copy into the container
  /containers/{name}/attach:
    post:
      description: 'Attach to a container to read its output or send it input. You can attach

        to the same container multiple times and you can reattach to containers

        that have been detached.


        It uses the same stream format as docker, see the libpod attach endpoint for a description of the format.

        '
      operationId: ContainerAttach
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: keys to use for detaching from the container
        in: query
        name: detachKeys
        schema:
          type: string
      - description: Stream all logs from the container across the connection. Happens before streaming attach (if requested). At least one of logs or stream must be set
        in: query
        name: logs
        schema:
          type: boolean
      - description: Attach to the container. If unset, and logs is set, only the container's logs will be sent. At least one of stream or logs must be set
        in: query
        name: stream
        schema:
          type: boolean
          default: true
      - description: Attach to container STDOUT
        in: query
        name: stdout
        schema:
          type: boolean
      - description: Attach to container STDERR
        in: query
        name: stderr
        schema:
          type: boolean
      - description: Attach to container STDIN
        in: query
        name: stdin
        schema:
          type: boolean
      responses:
        '101':
          description: No error, connection has been hijacked for transporting streams.
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Attach to a container
      tags:
      - containers (compat)
  /containers/{name}/changes:
    get:
      description: 'Returns which files in a container''s filesystem have been added, deleted, or modified. The Kind of modification can be one of:


        0: Modified

        1: Added

        2: Deleted

        '
      operationId: ContainerChanges
      parameters:
      - description: the name or id of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: specify a second layer which is used to compare against it instead of the parent layer
        in: query
        name: parent
        schema:
          type: string
      - description: select what you want to match, default is all
        in: query
        name: diffType
        schema:
          type: string
          enum:
          - all
          - container
          - image
      responses:
        '200':
          description: Array of Changes
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Report on changes to container's filesystem; adds, deletes or modifications.
      tags:
      - containers (compat)
  /containers/{name}/export:
    get:
      description: Export the contents of a container as a tarball.
      operationId: ContainerExport
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: tarball is returned in body
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Export a container
      tags:
      - containers (compat)
  /containers/{name}/json:
    get:
      description: Return low-level information about a container.
      operationId: ContainerInspect
      parameters:
      - description: the name or id of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: include the size of the container
        in: query
        name: size
        schema:
          type: boolean
          default: false
      responses:
        '200':
          $ref: '#/components/responses/containerInspectResponse'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Inspect container
      tags:
      - containers (compat)
  /containers/{name}/kill:
    post:
      description: Signal to send to the container as an integer or string (e.g. SIGINT)
      operationId: ContainerKill
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Send kill signal to all containers
        in: query
        name: all
        schema:
          type: boolean
          default: false
      - description: signal to be sent to container
        in: query
        name: signal
        schema:
          type: string
          default: SIGKILL
      responses:
        '204':
          description: no error
        '404':
          $ref: '#/components/responses/containerNotFound'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Kill container
      tags:
      - containers (compat)
  /containers/{name}/logs:
    get:
      description: Get stdout and stderr logs from a container.
      operationId: ContainerLogs
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Keep connection after returning logs.
        in: query
        name: follow
        schema:
          type: boolean
      - description: Return logs from stdout
        in: query
        name: stdout
        schema:
          type: boolean
      - description: Return logs from stderr
        in: query
        name: stderr
        schema:
          type: boolean
      - description: Only return logs since this time, as a UNIX timestamp
        in: query
        name: since
        schema:
          type: string
      - description: Only return logs before this time, as a UNIX timestamp
        in: query
        name: until
        schema:
          type: string
      - description: Add timestamps to every log line
        in: query
        name: timestamps
        schema:
          type: boolean
          default: false
      - description: Only return this number of log lines from the end of the logs
        in: query
        name: tail
        schema:
          type: string
          default: all
      responses:
        '200':
          description: logs returned as a stream in response body.
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Get container logs
      tags:
      - containers (compat)
  /containers/{name}/pause:
    post:
      description: Use the cgroups freezer to suspend all processes in a container.
      operationId: ContainerPause
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: no error
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Pause container
      tags:
      - containers (compat)
  /containers/{name}/rename:
    post:
      description: Change the name of an existing container.
      operationId: ContainerRename
      parameters:
      - description: Full or partial ID or full name of the container to rename
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: New name for the container
        in: query
        name: name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: no error
        '404':
          $ref: '#/components/responses/containerNotFound'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Rename an existing container
      tags:
      - containers (compat)
  /containers/{name}/resize:
    post:
      description: Resize the terminal attached to a container (for use with Attach).
      operationId: ContainerResize
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Height to set for the terminal, in characters
        in: query
        name: h
        schema:
          type: integer
      - description: Width to set for the terminal, in characters
        in: query
        name: w
        schema:
          type: integer
      - description: Ignore containers not running errors
        in: query
        name: running
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/ok'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Resize a container's TTY
      tags:
      - containers (compat)
  /containers/{name}/restart:
    post:
      operationId: ContainerRestart
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: timeout before sending kill signal to container
        in: query
        name: t
        schema:
          type: integer
      responses:
        '204':
          description: no error
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Restart container
      tags:
      - containers (compat)
  /containers/{name}/start:
    post:
      operationId: ContainerStart
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: 'Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.'
        in: query
        name: detachKeys
        schema:
          type: string
          default: ctrl-p,ctrl-q
      responses:
        '204':
          description: no error
        '304':
          $ref: '#/components/responses/containerAlreadyStartedError'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Start a container
      tags:
      - containers (compat)
  /containers/{name}/stats:
    get:
      description: This returns a live stream of a container’s resource usage statistics.
      operationId: ContainerStats
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Stream the output
        in: query
        name: stream
        schema:
          type: boolean
          default: true
      - description: Provide a one-shot response in which preCPU stats are blank, resulting in a single cycle return.
        in: query
        name: one-shot
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: no error
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Get stats for a container
      tags:
      - containers (compat)
  /containers/{name}/stop:
    post:
      description: Stop a container
      operationId: ContainerStop
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: number of seconds to wait before killing container
        in: query
        name: t
        schema:
          type: integer
      - description: Number of seconds to wait before killing the container (libpod alias for `t`).
        in: query
        name: timeout
        schema:
          type: integer
      - description: Do not return an error if the container is already stopped.
        in: query
        name: ignore
        schema:
          type: boolean
          default: false
      responses:
        '204':
          description: no error
        '304':
          $ref: '#/components/responses/containerAlreadyStoppedError'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Stop a container
      tags:
      - containers (compat)
  /containers/{name}/top:
    get:
      operationId: ContainerTop
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: arguments to pass to ps such as aux.
        in: query
        name: ps_args
        schema:
          type: string
          default: -ef
      responses:
        '200':
          $ref: '#/components/responses/containerTopResponse'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: List processes running inside a container
      tags:
      - containers (compat)
  /containers/{name}/unpause:
    post:
      description: Resume a paused container
      operationId: ContainerUnpause
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: no error
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Unpause container
      tags:
      - containers (compat)
  /containers/{name}/update:
    post:
      description: Change configuration settings for an existing container without requiring recreation.
      operationId: ContainerUpdate
      parameters:
      - description: Full or partial ID or full name of the container to rename
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: no error
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Update configuration of an existing container, allowing changes to resource limits
      tags:
      - containers (compat)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/containerUpdateRequest'
          application/x-tar:
            schema:
              $ref: '#/components/schemas/containerUpdateRequest'
        description: attributes for updating the container
  /containers/{name}/wait:
    post:
      description: 'Block until a container stops or given condition is met.

        This is a Docker-compatible endpoint.

        '
      operationId: ContainerWait
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: "Wait condition.  Valid values are:\n  - not-running (default) - return when the container is not running\n    (stopped, exited, or was never started).\n  - next-exit - wait for the next time the container stops.\n    If the container is running, block until it exits.\n    If the container is already stopped, block until\n    the next start-and-exit cycle.\n  - removed - wait until the container is removed.\n"
        in: query
        name: condition
        schema:
          type: string
          default: not-running
      responses:
        '200':
          $ref: '#/components/responses/containerWaitResponse'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Wait on a container
      tags:
      - containers (compat)
  /containers/create:
    post:
      operationId: ContainerCreate
      parameters:
      - description: container name
        in: query
        name: name
        schema:
          type: string
      responses:
        '201':
          $ref: '#/components/responses/containerCreateResponse'
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Create a container
      tags:
      - containers (compat)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContainerConfig'
          application/x-tar:
            schema:
              $ref: '#/components/schemas/CreateContainerConfig'
        description: Container to create
        required: true
  /containers/json:
    get:
      description: Returns a list of containers
      operationId: ContainerList
      parameters:
      - description: Return all containers. By default, only running containers are shown
        in: query
        name: all
        schema:
          type: boolean
          default: false
      - description: Return containers in storage not controlled by Podman
        in: query
        name: external
        schema:
          type: boolean
          default: false
      - description: Return this number of most recently created containers, including non-running ones.
        in: query
        name: limit
        schema:
          type: integer
      - description: Return the size of container as fields SizeRw and SizeRootFs.
        in: query
        name: size
        schema:
          type: boolean
          default: false
      - description: 'A JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters:

          - `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

          - `before`=(`<container id>` or `<container name>`)

          - `expose`=(`<port>[/<proto>]` or `<startport-endport>/[<proto>]`)

          - `exited=<int>` containers with exit code of `<int>`

          - `health`=(`starting`, `healthy`, `unhealthy` or `none`)

          - `id=<ID>` a container''s ID

          - `is-task`=(`true` or `false`)

          - `label`=(`key` or `"key=value"`) of a container label

          - `name=<name>` a container''s name

          - `network`=(`<network id>` or `<network name>`)

          - `publish`=(`<port>[/<proto>]` or `<startport-endport>/[<proto>]`)

          - `since`=(`<container id>` or `<container name>`)

          - `status`=(`created`, `restarting`, `running`, `removing`, `paused`, `exited` or `dead`)

          - `volume`=(`<volume name>` or `<mount point destination>`)

          '
        in: query
        name: filters
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/containersList'
        '400':
          $ref: '#/components/responses/badParamError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: List containers
      tags:
      - containers (compat)
  /containers/prune:
    post:
      description: Remove containers not in use
      operationId: ContainerPrune
      parameters:
      - description: "Filters to process on the prune list, encoded as JSON (a `map[string][]string`).  Available filters:\n - `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.\n - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels.\n"
        in: query
        name: filters
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/containersPrune'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Delete stopped containers
      tags:
      - containers (compat)
  /libpod/containers/{name}/archive:
    get:
      description: Copy a tar archive of files from a container
      operationId: ContainerArchiveLibpod
      parameters:
      - description: container name or id
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Path to a directory in the container to extract
        in: query
        name: path
        required: true
        schema:
          type: string
      - description: JSON encoded map[string]string to translate paths
        in: query
        name: rename
        schema:
          type: string
      responses:
        '200':
          description: no error
          content:
            application/json:
              schema:
                format: binary
                type: string
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Copy files from a container
      tags:
      - containers (compat)
components:
  schemas:
    PortMap:
      additionalProperties:
        items:
          properties:
            HostIp:
              description: HostIP is the host IP Address
              type: string
              x-go-name: HostIP
              x-go-type: net/netip.Addr
            HostPort:
              description: HostPort is the host port number
              type: string
          type: object
        type: array
      title: PortMap is a collection of [PortBinding] indexed by [Port].
      type: object
      x-go-package: github.com/moby/moby/api/types/network
    Digest:
      description: 'The following is an example of the contents of Digest types:


        sha256:7173b809ca12ec5dee4506cd86be934c4596dd234ee82c0662eac04a8c2c71dc


        This allows to abstract the digest behind this type and work only in those

        terms.'
      title: 'Digest allows simple protection of hex formatted digest strings, prefixed

        by their algorithm. Strings of type Digest have some guarantee of being in

        the correct format and it provides quick access to the components of a

        digest string.'
      type: string
      x-go-package: github.com/opencontainers/go-digest
    ClusterOptions:
      title: ClusterOptions specifies options for a Cluster volume.
      type: object
      x-go-package: github.com/moby/moby/api/types/mount
    FileMode:
      description: 'The bits have the same definition on all systems, so that

        information about files can be moved from one system

        to another portably. Not all bits apply to all systems.

        The only required bit is [ModeDir] for directories.'
      format: uint32
      title: A FileMode represents a file's mode and permission bits.
      type: integer
      x-go-package: os
    PidMode:
      title: PidMode represents the pid namespace of the container.
      type: string
      x-go-package: github.com/moby/moby/api/types/container
    Propagation:
      title: Propagation represents the propagation of a mount.
      type: string
  

# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/podman/refs/heads/main/openapi/podman-containers-compat-api-openapi.yml