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. 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 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 checks
      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:
  schemas:
    NetworkBackend:
      type: string
      x-go-package: go.podman.io/common/libnetwork/types
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
  responses:
    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'
    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'
    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'
    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'
    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'
    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'
    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'