Podman containers 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 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
  name: containers
paths:
  /libpod/commit:
    post:
      description: Create a new image from a container
      operationId: ImageCommitLibpod
      parameters:
      - description: the name or ID of a container
        in: query
        name: container
        required: true
        schema:
          type: string
      - description: author of the image
        in: query
        name: author
        schema:
          type: string
      - description: instructions to apply while committing in Dockerfile format (i.e. "CMD=/bin/foo")
        in: query
        name: changes
        schema:
          type: array
          items:
            type: string
      - description: commit message
        in: query
        name: comment
        schema:
          type: string
      - description: format of the image manifest and metadata (default "oci")
        in: query
        name: format
        schema:
          type: string
      - description: pause the container before committing it
        in: query
        name: pause
        schema:
          type: boolean
      - description: squash the container before committing it
        in: query
        name: squash
        schema:
          type: boolean
      - description: the repository name for the created image
        in: query
        name: repo
        schema:
          type: string
      - description: output from commit process
        in: query
        name: stream
        schema:
          type: boolean
      - description: tag name for the created image
        in: query
        name: tag
        schema:
          type: string
      responses:
        '201':
          description: no error
        '404':
          $ref: '#/components/responses/imageNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Commit
      tags:
      - containers
  /libpod/containers/{name}:
    delete:
      description: Delete container
      operationId: ContainerDeleteLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: additionally remove containers that depend on the container to be removed
        in: query
        name: depend
        schema:
          type: boolean
      - description: force stop container if running
        in: query
        name: force
        schema:
          type: boolean
      - description: ignore errors when the container to be removed does not existxo
        in: query
        name: ignore
        schema:
          type: boolean
      - description: number of seconds to wait before killing container when force removing
        in: query
        name: timeout
        schema:
          type: integer
          default: 10
      - description: delete volumes
        in: query
        name: v
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/containerRemoveLibpod'
        '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: Delete container
      tags:
      - containers
  /libpod/containers/{name}/archive:
    put:
      description: Copy a tar archive of files into a container
      operationId: PutContainerArchiveLibpod
      parameters:
      - description: container name or id
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Path to a directory in the container to extract
        in: query
        name: path
        required: true
        schema:
          type: string
      - description: pause the container while copying (defaults to true)
        in: query
        name: pause
        schema:
          type: boolean
          default: true
      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: Copy files into a container
      tags:
      - containers
      requestBody:
        content:
          application/json:
            schema:
              type: string
          application/x-tar:
            schema:
              type: string
        description: tarfile of files to copy into the container
  /libpod/containers/{name}/attach:
    post:
      description: 'Attach to a container to read its output or send it input. You can attach

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

        that have been detached.


        ### Hijacking


        This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`,

        and `stderr` on the same socket.


        This is the response from the service for an attach request:


        ```

        HTTP/1.1 200 OK

        Content-Type: application/vnd.docker.raw-stream


        [STREAM]

        ```


        After the headers and two new lines, the TCP connection can now be used

        for raw, bidirectional communication between the client and server.


        To inform potential proxies about connection hijacking, the client

        can also optionally send connection upgrade headers.


        For example, the client sends this request to upgrade the connection:


        ```

        POST /v4.6.0/libpod/containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1

        Upgrade: tcp

        Connection: Upgrade

        ```


        The service will respond with a `101 UPGRADED` response, and will

        similarly follow with the raw stream:


        ```

        HTTP/1.1 101 UPGRADED

        Content-Type: application/vnd.docker.raw-stream

        Connection: Upgrade

        Upgrade: tcp


        [STREAM]

        ```


        ### Stream format


        When the TTY setting is disabled for the container,

        the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream

        (starting with v4.7.0, previously application/vnd.docker.raw-stream was always used)

        and the stream over the hijacked connected is multiplexed to separate out

        `stdout` and `stderr`. The stream consists of a series of frames, each

        containing a header and a payload.


        The header contains the information about the output stream type and the size of

        the payload.

        It is encoded on the first eight bytes like this:


        ```go

        header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}

        ```


        `STREAM_TYPE` can be:


        - 0: `stdin` (is written on `stdout`)

        - 1: `stdout`

        - 2: `stderr`


        `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size

        encoded as big endian.


        Following the header is the payload, which contains the specified number of

        bytes as written in the size.


        The simplest way to implement this protocol is the following:


        1. Read 8 bytes.

        2. Choose `stdout` or `stderr` depending on the first byte.

        3. Extract the frame size from the last four bytes.

        4. Read the extracted size and output it on the correct output.

        5. Goto 1.


        ### Stream format when using a TTY


        When the TTY setting is enabled for the container,

        the stream is not multiplexed. The data exchanged over the hijacked

        connection is simply the raw data from the process PTY and client''s

        `stdin`.

        '
      operationId: ContainerAttachLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        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
  /libpod/containers/{name}/changes:
    get:
      description: 'Returns which files in a container''s filesystem have been added, deleted, or modified. The Kind of modification can be one of:


        0: Modified

        1: Added

        2: Deleted

        '
      operationId: ContainerChangesLibpod
      parameters:
      - description: the name or id of the container
        in: path
        name: name
        required: true
        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
  /libpod/containers/{name}/checkpoint:
    post:
      operationId: ContainerCheckpointLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: keep all temporary checkpoint files
        in: query
        name: keep
        schema:
          type: boolean
      - description: leave the container running after writing checkpoint to disk
        in: query
        name: leaveRunning
        schema:
          type: boolean
      - description: checkpoint a container with established TCP connections
        in: query
        name: tcpEstablished
        schema:
          type: boolean
      - description: export the checkpoint image to a tar.gz
        in: query
        name: export
        schema:
          type: boolean
      - description: do not include root file-system changes when exporting. can only be used with export
        in: query
        name: ignoreRootFS
        schema:
          type: boolean
      - description: do not include associated volumes. can only be used with export
        in: query
        name: ignoreVolumes
        schema:
          type: boolean
      - description: dump the container's memory information only, leaving the container running. only works on runc 1.0-rc or higher
        in: query
        name: preCheckpoint
        schema:
          type: boolean
      - description: check out the container with previous criu image files in pre-dump. only works on runc 1.0-rc or higher
        in: query
        name: withPrevious
        schema:
          type: boolean
      - description: checkpoint a container with filelocks
        in: query
        name: fileLocks
        schema:
          type: boolean
      - description: add checkpoint statistics to the returned CheckpointReport
        in: query
        name: printStats
        schema:
          type: boolean
      responses:
        '200':
          description: tarball is returned in body if exported
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Checkpoint a container
      tags:
      - containers
  /libpod/containers/{name}/exists:
    get:
      description: Quick way to determine if a container exists by name or ID
      operationId: ContainerExistsLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: container exists
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Check if container exists
      tags:
      - containers
  /libpod/containers/{name}/export:
    get:
      description: Export the contents of a container as a tarball.
      operationId: ContainerExportLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        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
  /libpod/containers/{name}/healthcheck:
    get:
      description: Execute the defined healthcheck and return information about the results
      operationId: ContainerHealthcheckLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/healthCheck'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '409':
          description: container has no healthcheck or is not running
        '500':
          $ref: '#/components/responses/internalError'
      summary: Run a container's healthcheck
      tags:
      - containers
  /libpod/containers/{name}/init:
    post:
      description: Performs all tasks necessary for initializing the container but does not start the container.
      operationId: ContainerInitLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: no error
        '304':
          description: container already initialized
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Initialize a container
      tags:
      - containers
  /libpod/containers/{name}/json:
    get:
      description: Return low-level information about a container.
      operationId: ContainerInspectLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: display filesystem usage
        in: query
        name: size
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/containerInspectResponseLibpod'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Inspect container
      tags:
      - containers
  /libpod/containers/{name}/kill:
    post:
      description: send a signal to a container, defaults to killing the container
      operationId: ContainerKillLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: signal to be sent to container, either by integer or SIG_ name
        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
  /libpod/containers/{name}/logs:
    get:
      description: 'Get stdout and stderr logs from a container.


        The stream format is the same as described in the attach endpoint.

        '
      operationId: ContainerLogsLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        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
  /libpod/containers/{name}/mount:
    post:
      description: Mount a container to the filesystem
      operationId: ContainerMountLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Include external containers that are not managed by Podman.
        in: query
        name: external
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: mounted container
          content:
            application/json:
              schema:
                description: id
                example: /var/lib/containers/storage/overlay/f3f693bd88872a1e3193f4ebb925f4c282e8e73aadb8ab3e7492754dda3a02a4/merged
                type: string
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Mount a container
      tags:
      - containers
  /libpod/containers/{name}/pause:
    post:
      description: Use the cgroups freezer to suspend all processes in a container.
      operationId: ContainerPauseLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: no error
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Pause a container
      tags:
      - containers
  /libpod/containers/{name}/rename:
    post:
      description: Change the name of an existing container.
      operationId: ContainerRenameLibpod
      parameters:
      - description: Full or partial ID or full name of the container to rename
        in: path
        name: name
        required: true
        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
  /libpod/containers/{name}/resize:
    post:
      description: Resize the terminal attached to a container (for use with Attach).
      operationId: ContainerResizeLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        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'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Resize a container's TTY
      tags:
      - containers
  /libpod/containers/{name}/restart:
    post:
      operationId: ContainerRestartLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: number of seconds to wait before killing container (Docker compatibility)
        in: query
        name: t
        schema:
          type: integer
      - description: number of seconds to wait before killing container
        in: query
        name: timeout
        schema:
          type: integer
      responses:
        '204':
          description: no error
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Restart a container
      tags:
      - containers
  /libpod/containers/{name}/restore:
    post:
      description: Restore a container from a checkpoint.
      operationId: ContainerRestoreLibpod
      parameters:
      - description: the name or id of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: the name of the container when restored from a tar. can only be used with import
        in: query
        name: name
        schema:
          type: string
      - description: keep all temporary checkpoint files
        in: query
        name: keep
        schema:
          type: boolean
      - description: restore a container with established TCP connections
        in: query
        name: tcpEstablished
        schema:
          type: boolean
      - description: restore a container but close the TCP connections
        in: query
        name: tcpClose
        schema:
          type: boolean
      - description: import the restore from a checkpoint tar.gz
        in: query
        name: import
        schema:
          type: boolean
      - description: do not include root file-system changes when exporting. can only be used with import
        in: query
        name: ignoreRootFS
        schema:
          type: boolean
      - description: do not restore associated volumes. can only be used with import
        in: query
        name: ignoreVolumes
        schema:
          type: boolean
      - description: ignore IP address if set statically
        in: query
        name: ignoreStaticIP
        schema:
          type: boolean
      - description: ignore MAC address if set statically
        in: query
        name: ignoreStaticMAC
        schema:
          type: boolean
      - description: restore a container with file locks
        in: query
        name: fileLocks
        schema:
          type: boolean
      - description: add restore statistics to the returned RestoreReport
        in: query
        name: printStats
        schema:
          type: boolean
      - description: pod to restore into
        in: query
        name: pod
        schema:
          type: string
      responses:
        '200':
          description: tarball is returned in body if exported
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Restore a container
      tags:
      - containers
  /libpod/containers/{name}/start:
    post:
      operationId: ContainerStartLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        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
  /libpod/containers/{name}/stats:
    get:
      description: DEPRECATED. This endpoint will be removed with the next major release. Please use /libpod/containers/stats instead.
      operationId: ContainerStatsLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Stream the output
        in: query
        name: stream
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: no error
        '404':
          $ref: '#/components/responses/containerNotFound'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Get stats for a container
      tags:
      - containers
  /libpod/containers/{name}/stop:
    post:
      operationId: ContainerStopLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: number of seconds to wait before killing container
        in: query
        name: timeout
        schema:
          type: integer
          default: 10
      - description: do not return error if 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
  /libpod/containers/{name}/top:
    get:
      description: List processes running inside a container
      operationId: ContainerTopLibpod
      parameters:
      - description: Name of container to query for processes (As of version 1.xx)
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: when true, repeatedly stream the latest output (As of version 4.0)
        in: query
        name: stream
        schema:
          type: boolean
      - description: if streaming, delay in seconds between updates. Must be >1. (As of version 4.0)
        in: query
        name: delay
        schema:
          type: integer
          default: 5
      - description: 'arguments to pass to ps such as aux.

          '
        in: query
        name: ps_args
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/containerTopResponse'
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: List processes
      tags:
      - containers
  /libpod/containers/{name}/unmount:
    post:
      description: Unmount a container from the filesystem
      operationId: ContainerUnmountLibpod
      parameters:
      - description: the name or ID of the container
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ok
        '404':
          $ref: '#/components/responses/containerNotFound'
        '500':
        

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