Podman System 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.
  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 System 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 Podman engine
  name: System
paths:
  /libpod/_ping:
    get:
      description: '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.'
      operationId: SystemPing
      responses:
        '200':
          description: Success
          headers:
            API-Version:
              description: Max compatibility API Version the server supports
              schema:
                type: string
            BuildKit-Version:
              description: Default version of docker image builder
              schema:
                type: string
            Cache-Control:
              description: always no-cache
              schema:
                type: string
            Docker-Experimental:
              description: If the server is running with experimental mode enabled, always true
              schema:
                type: boolean
            Libpod-API-Version:
              description: 'Max Podman API Version the server supports.

                Available if service is backed by Podman, therefore may be used to

                determine if talking to Podman engine or another engine

                '
              schema:
                type: string
            Libpod-Buildah-Version:
              description: "Default version of libpod image builder.\n  Available if service is backed by Podman, therefore may be used to\n  determine if talking to Podman engine or another engine\n"
              schema:
                type: string
            Pragma:
              description: always no-cache
              schema:
                type: string
          content:
            text/plain:
              schema:
                description: OK
                example: OK
                type: string
        '500':
          $ref: '#/components/responses/internalError'
      summary: Ping service
      tags:
      - System
  /libpod/events:
    get:
      description: Returns events filtered on query parameters
      operationId: SystemEventsLibpod
      parameters:
      - description: start streaming events from this time
        in: query
        name: since
        schema:
          type: string
      - description: stop streaming events later than this
        in: query
        name: until
        schema:
          type: string
      - description: JSON encoded map[string][]string of constraints
        in: query
        name: filters
        schema:
          type: string
      - description: when false, do not follow events
        in: query
        name: stream
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: returns a string of json data describing an event
        '500':
          $ref: '#/components/responses/internalError'
      summary: Get events
      tags:
      - System
  /libpod/info:
    get:
      description: Returns information on the system and libpod configuration
      operationId: SystemInfoLibpod
      responses:
        '200':
          $ref: '#/components/responses/infoResponse'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Get info
      tags:
      - System
  /libpod/system/check:
    post:
      operationId: SystemCheckLibpod
      parameters:
      - description: Skip time-consuming checks
        in: query
        name: quick
        schema:
          type: boolean
      - description: Remove inconsistent images
        in: query
        name: repair
        schema:
          type: boolean
      - description: Remove inconsistent containers and images
        in: query
        name: repair_lossy
        schema:
          type: boolean
      - description: Maximum allowed age of unreferenced layers
        in: query
        name: unreferenced_layer_max_age
        schema:
          type: string
          default: 24h0m0s
      responses:
        '200':
          $ref: '#/components/responses/systemCheckResponse'
        '400':
          $ref: '#/components/responses/badParamError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Performs consistency checks on storage, optionally removing items which fail…
      tags:
      - System
  /libpod/system/df:
    get:
      description: Return information about disk usage for containers, images, and volumes
      operationId: SystemDataUsageLibpod
      responses:
        '200':
          $ref: '#/components/responses/systemDiskUsage'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Show disk usage
      tags:
      - System
  /libpod/system/prune:
    post:
      operationId: SystemPruneLibpod
      parameters:
      - description: Remove all unused data, not just dangling data
        in: query
        name: all
        schema:
          type: boolean
      - description: Prune volumes
        in: query
        name: volumes
        schema:
          type: boolean
      - description: Remove images used by external containers (e.g., build containers)
        in: query
        name: external
        schema:
          type: boolean
      - description: Remove build cache
        in: query
        name: build
        schema:
          type: boolean
      - description: "JSON encoded value of filters (a map[string][]string) to match data against before pruning.\nAvailable filters:\n  - `until=<timestamp>` Prune data 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 data with (or without, in case `label!=...` is used) the specified labels.\n"
        in: query
        name: filters
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/systemPruneResponse'
        '400':
          $ref: '#/components/responses/badParamError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Prune unused data
      tags:
      - System
  /libpod/version:
    get:
      operationId: SystemVersionLibpod
      responses:
        '200':
          $ref: '#/components/responses/versionResponse'
      summary: Component Version information
      tags:
      - System
components:
  responses:
    infoResponse:
      description: Info
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LibpodInfo'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/LibpodInfo'
        text/plain:
          schema:
            $ref: '#/components/schemas/LibpodInfo'
    badParamError:
      description: Bad parameter in request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/ErrorModel'
        text/plain:
          schema:
            $ref: '#/components/schemas/ErrorModel'
    internalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/ErrorModel'
        text/plain:
          schema:
            $ref: '#/components/schemas/ErrorModel'
    versionResponse:
      description: Version
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ComponentVersion'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/ComponentVersion'
        text/plain:
          schema:
            $ref: '#/components/schemas/ComponentVersion'
    systemPruneResponse:
      description: System Prune results
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SystemPruneReport'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/SystemPruneReport'
        text/plain:
          schema:
            $ref: '#/components/schemas/SystemPruneReport'
    systemDiskUsage:
      description: Disk usage
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SystemDfReport'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/SystemDfReport'
        text/plain:
          schema:
            $ref: '#/components/schemas/SystemDfReport'
    systemCheckResponse:
      description: Check
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SystemCheckReport'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/SystemCheckReport'
        text/plain:
          schema:
            $ref: '#/components/schemas/SystemCheckReport'
  schemas:
    NetworkInfo:
      properties:
        backend:
          $ref: '#/components/schemas/NetworkBackend'
        defaultNetwork:
          type: string
          x-go-name: DefaultNetwork
        dns:
          $ref: '#/components/schemas/DNSNetworkInfo'
        package:
          type: string
          x-go-name: Package
        path:
          type: string
          x-go-name: Path
        version:
          type: string
          x-go-name: Version
      title: NetworkInfo contains the network information.
      type: object
      x-go-package: go.podman.io/common/libnetwork/types
    LibpodInfo:
      description: 'Info is the overall struct that describes the host system

        running libpod/podman'
      properties:
        host:
          $ref: '#/components/schemas/HostInfo'
        plugins:
          $ref: '#/components/schemas/Plugins'
        registries:
          additionalProperties: {}
          type: object
          x-go-name: Registries
        store:
          $ref: '#/components/schemas/StoreInfo'
        version:
          $ref: '#/components/schemas/Version'
      type: object
      x-go-name: Info
      x-go-package: go.podman.io/podman/v6/libpod/define
    CPUUsage:
      properties:
        idlePercent:
          format: double
          type: number
          x-go-name: IdlePercent
        systemPercent:
          format: double
          type: number
          x-go-name: SystemPercent
        userPercent:
          format: double
          type: number
          x-go-name: UserPercent
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    StoreInfo:
      description: 'StoreInfo describes the container storage and its

        attributes'
      properties:
        containerStore:
          $ref: '#/components/schemas/ContainerStore'
        graphDriverName:
          type: string
          x-go-name: GraphDriverName
        graphOptions:
          additionalProperties: {}
          type: object
          x-go-name: GraphOptions
        graphRoot:
          type: string
          x-go-name: GraphRoot
        graphRootAllocated:
          description: GraphRootAllocated is how much space the graphroot has in bytes
          format: uint64
          type: integer
          x-go-name: GraphRootAllocated
        graphRootUsed:
          description: GraphRootUsed is how much of graphroot is used in bytes
          format: uint64
          type: integer
          x-go-name: GraphRootUsed
        graphStatus:
          additionalProperties:
            type: string
          type: object
          x-go-name: GraphStatus
        imageCopyTmpDir:
          type: string
          x-go-name: ImageCopyTmpDir
        imageStore:
          $ref: '#/components/schemas/ImageStore'
        runRoot:
          type: string
          x-go-name: RunRoot
        transientStore:
          type: boolean
          x-go-name: TransientStore
        volumePath:
          type: string
          x-go-name: VolumePath
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    DNSNetworkInfo:
      properties:
        package:
          type: string
          x-go-name: Package
        path:
          type: string
          x-go-name: Path
        version:
          type: string
          x-go-name: Version
      title: DNSNetworkInfo contains the DNS information.
      type: object
      x-go-package: go.podman.io/common/libnetwork/types
    ConmonInfo:
      description: ConmonInfo describes the conmon executable being used
      properties:
        package:
          type: string
          x-go-name: Package
        path:
          type: string
          x-go-name: Path
        version:
          type: string
          x-go-name: Version
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    NetworkBackend:
      type: string
      x-go-package: go.podman.io/common/libnetwork/types
    ImageStore:
      description: 'ImageStore describes the image store.  Right now only the number

        of images present'
      properties:
        number:
          format: int64
          type: integer
          x-go-name: Number
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    DistributionInfo:
      description: DistributionInfo describes the host distribution for libpod
      properties:
        codename:
          type: string
          x-go-name: Codename
        distribution:
          type: string
          x-go-name: Distribution
        variant:
          type: string
          x-go-name: Variant
        version:
          type: string
          x-go-name: Version
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    OCIRuntimeInfo:
      description: 'OCIRuntimeInfo describes the runtime (crun or runc) being

        used with podman'
      properties:
        name:
          type: string
          x-go-name: Name
        package:
          type: string
          x-go-name: Package
        path:
          type: string
          x-go-name: Path
        version:
          type: string
          x-go-name: Version
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    ComponentVersion:
      description: ServiceOptions provides the input for starting an API and sidecar pprof services
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities
    Version:
      description: Version is an output struct for API
      properties:
        APIVersion:
          type: string
        BuildOrigin:
          type: string
        Built:
          format: int64
          type: integer
        BuiltTime:
          type: string
        GitCommit:
          type: string
        GoVersion:
          type: string
        Os:
          type: string
        OsArch:
          type: string
        Version:
          type: string
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    IDMappings:
      description: IDMappings describe the GID and UID mappings
      properties:
        gidmap:
          items:
            $ref: '#/components/schemas/IDMap'
          type: array
          x-go-name: GIDMap
        uidmap:
          items:
            $ref: '#/components/schemas/IDMap'
          type: array
          x-go-name: UIDMap
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    Plugins:
      properties:
        authorization:
          description: Authorization is provided for compatibility, will always be nil as Podman has no daemon
          items:
            type: string
          type: array
          x-go-name: Authorization
        log:
          items:
            type: string
          type: array
          x-go-name: Log
        network:
          items:
            type: string
          type: array
          x-go-name: Network
        volume:
          items:
            type: string
          type: array
          x-go-name: Volume
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    SystemDfReport:
      description: ServiceOptions provides the input for starting an API and sidecar pprof services
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities
    SecurityInfo:
      description: SecurityInfo describes the libpod host
      properties:
        apparmorEnabled:
          type: boolean
          x-go-name: AppArmorEnabled
        capabilities:
          type: string
          x-go-name: DefaultCapabilities
        rootless:
          type: boolean
          x-go-name: Rootless
        seccompEnabled:
          type: boolean
          x-go-name: SECCOMPEnabled
        seccompProfilePath:
          type: string
          x-go-name: SECCOMPProfilePath
        selinuxEnabled:
          type: boolean
          x-go-name: SELinuxEnabled
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    ErrorModel:
      description: ErrorModel is used in remote connections with podman
      properties:
        cause:
          description: API root cause formatted for automated parsing
          example: API root cause
          type: string
          x-go-name: Because
        message:
          description: human error message, formatted for a human to read
          example: human error message
          type: string
          x-go-name: Message
        response:
          description: HTTP response code
          format: int64
          minimum: 400
          type: integer
          x-go-name: ResponseCode
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/errorhandling
    IDMap:
      description: 'IDMap contains a single entry for user namespace range remapping. An array

        of IDMap entries represents the structure that will be provided to the Linux

        kernel for creating a user namespace.'
      properties:
        container_id:
          format: int64
          type: integer
          x-go-name: ContainerID
        host_id:
          format: int64
          type: integer
          x-go-name: HostID
        size:
          format: int64
          type: integer
          x-go-name: Size
      type: object
      x-go-package: go.podman.io/storage/pkg/idtools
    SystemPruneReport:
      description: ServiceOptions provides the input for starting an API and sidecar pprof services
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities
    PastaInfo:
      description: PastaInfo describes the pasta executable that is being used
      properties:
        executable:
          type: string
          x-go-name: Executable
        package:
          type: string
          x-go-name: Package
        version:
          type: string
          x-go-name: Version
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    HostInfo:
      description: HostInfo describes the libpod host
      properties:
        arch:
          type: string
          x-go-name: Arch
        buildahVersion:
          type: string
          x-go-name: BuildahVersion
        cgroupControllers:
          items:
            type: string
          type: array
          x-go-name: CgroupControllers
        cgroupManager:
          type: string
          x-go-name: CgroupManager
        cgroupVersion:
          type: string
          x-go-name: CgroupsVersion
        conmon:
          $ref: '#/components/schemas/ConmonInfo'
        cpuUtilization:
          $ref: '#/components/schemas/CPUUsage'
        cpus:
          format: int64
          type: integer
          x-go-name: CPUs
        databaseBackend:
          type: string
          x-go-name: DatabaseBackend
        distribution:
          $ref: '#/components/schemas/DistributionInfo'
        emulatedArchitectures:
          items:
            type: string
          type: array
          x-go-name: EmulatedArchitectures
        eventLogger:
          type: string
          x-go-name: EventLogger
        freeLocks:
          format: uint32
          type: integer
          x-go-name: FreeLocks
        hostname:
          type: string
          x-go-name: Hostname
        idMappings:
          $ref: '#/components/schemas/IDMappings'
        kernel:
          type: string
          x-go-name: Kernel
        linkmode:
          type: string
          x-go-name: Linkmode
        logDriver:
          type: string
          x-go-name: LogDriver
        memFree:
          format: int64
          type: integer
          x-go-name: MemFree
        memTotal:
          format: int64
          type: integer
          x-go-name: MemTotal
        networkBackend:
          type: string
          x-go-name: NetworkBackend
        networkBackendInfo:
          $ref: '#/components/schemas/NetworkInfo'
        ociRuntime:
          $ref: '#/components/schemas/OCIRuntimeInfo'
        os:
          type: string
          x-go-name: OS
        pasta:
          $ref: '#/components/schemas/PastaInfo'
        remoteSocket:
          $ref: '#/components/schemas/RemoteSocket'
        rootlessNetworkCmd:
          description: RootlessNetworkCmd returns the default rootless network command (pasta)
          type: string
          x-go-name: RootlessNetworkCmd
        runtimeInfo:
          additionalProperties: {}
          type: object
          x-go-name: RuntimeInfo
        security:
          $ref: '#/components/schemas/SecurityInfo'
        serviceIsRemote:
          description: ServiceIsRemote is true when the podman/libpod service is remote to the client
          type: boolean
          x-go-name: ServiceIsRemote
        swapFree:
          format: int64
          type: integer
          x-go-name: SwapFree
        swapTotal:
          format: int64
          type: integer
          x-go-name: SwapTotal
        uptime:
          type: string
          x-go-name: Uptime
        variant:
          type: string
          x-go-name: Variant
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    RemoteSocket:
      description: RemoteSocket describes information about the API socket
      properties:
        exists:
          type: boolean
          x-go-name: Exists
        path:
          type: string
          x-go-name: Path
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define
    SystemCheckReport:
      description: ServiceOptions provides the input for starting an API and sidecar pprof services
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities
    ContainerStore:
      description: 'ContainerStore describes the quantity of containers in the

        store by status'
      properties:
        number:
          format: int64
          type: integer
          x-go-name: Number
        paused:
          format: int64
          type: integer
          x-go-name: Paused
        running:
          format: int64
          type: integer
          x-go-name: Running
        stopped:
          format: int64
          type: integer
          x-go-name: Stopped
      type: object
      x-go-package: go.podman.io/podman/v6/libpod/define