swagger: '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 volumes (compat) API
  version: 5.0.0
  x-logo:
  - url: https://raw.githubusercontent.com/containers/libpod/main/logo/podman-logo.png
  - altText: Podman logo
host: podman.io
basePath: /
schemes:
- http
- https
consumes:
- application/json
- application/x-tar
produces:
- application/json
- application/octet-stream
- text/plain
tags:
- description: Actions related to volumes for the compatibility endpoints
  name: volumes (compat)
paths:
  /volumes:
    get:
      description: Returns a list of volume
      operationId: VolumeList
      parameters:
      - description: "JSON encoded value of the filters (a map[string][]string) to process on the volumes list. Available filters:\n  - driver=<volume-driver-name> Matches volumes based on their driver.\n  - label=<key> or label=<key>:<value> Matches volumes based on the presence of a label alone or a label and a value.\n  - name=<volume-name> Matches all of volume name.\n  - `until=<timestamp>` List volumes 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\nNote:\n  The boolean `dangling` filter is not yet implemented for this endpoint.\n"
        in: query
        name: filters
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/volumeList'
        '500':
          $ref: '#/responses/internalError'
      summary: List volumes
      tags:
      - volumes (compat)
  /volumes/{name}:
    delete:
      operationId: VolumeDelete
      parameters:
      - description: the name or ID of the volume
        in: path
        name: name
        required: true
        type: string
      - description: 'Force removal of the volume. This actually only causes errors due

          to the names volume not being found to be suppressed, which is the

          behaviour Docker implements.

          '
        in: query
        name: force
        type: boolean
      - description: timeout before forcibly killing any containers using the volume
        in: query
        name: timeout
        type: integer
      produces:
      - application/json
      responses:
        '204':
          description: no error
        '404':
          $ref: '#/responses/volumeNotFound'
        '409':
          description: Volume is in use and cannot be removed
        '500':
          $ref: '#/responses/internalError'
      summary: Remove volume
      tags:
      - volumes (compat)
    get:
      operationId: VolumeInspect
      parameters:
      - description: the name or ID of the volume
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/volumeInspect'
        '500':
          $ref: '#/responses/internalError'
      summary: Inspect volume
      tags:
      - volumes (compat)
  /volumes/create:
    post:
      operationId: VolumeCreate
      parameters:
      - description: 'attributes for creating a volume.

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

          '
        in: body
        name: create
        schema:
          $ref: '#/definitions/volumeCreate'
      produces:
      - application/json
      responses:
        '201':
          $ref: '#/responses/volumeInspect'
        '500':
          $ref: '#/responses/internalError'
      summary: Create a volume
      tags:
      - volumes (compat)
  /volumes/prune:
    post:
      operationId: VolumePrune
      parameters:
      - description: "JSON encoded value of filters (a map[string][]string). Docker API 1.42+ - by default only anonymous (unnamed) unused volumes are pruned; use filter all=true to prune all unused volumes.\nAvailable filters:\n  - `all` When true, prune all unused volumes (anonymous and named). When false or unset, only anonymous unused volumes are pruned.\n  - `until=<timestamp>` Prune volumes 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 volumes with (or without, in case `label!=...` is used) the specified labels.\n"
        in: query
        name: filters
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/volumePruneResponse'
        '500':
          $ref: '#/responses/internalError'
      summary: Prune volumes
      tags:
      - volumes (compat)
definitions:
  Availability:
    title: Availability specifies the availability of the volume.
    type: string
    x-go-package: github.com/moby/moby/api/types/volume
  Scope:
    description: 'Scope defines the Scope of a Cluster Volume. This is how many nodes a

      Volume can be accessed simultaneously on.'
    type: string
    x-go-package: github.com/moby/moby/api/types/volume
  Volume:
    description: Volume volume
    properties:
      ClusterVolume:
        $ref: '#/definitions/ClusterVolume'
      CreatedAt:
        description: Date/Time the volume was created.
        example: '2016-06-07T20:31:11.853781916Z'
        type: string
      Driver:
        description: Name of the volume driver used by the volume.
        example: custom
        type: string
      Labels:
        additionalProperties:
          type: string
        description: User-defined key/value metadata.
        example:
          com.example.some-label: some-value
          com.example.some-other-label: some-other-value
        type: object
      Mountpoint:
        description: Mount path of the volume on the host.
        example: /var/lib/docker/volumes/tardis
        type: string
      Name:
        description: Name of the volume.
        example: tardis
        type: string
      Options:
        additionalProperties:
          type: string
        description: The driver specific options used when creating the volume.
        example:
          device: tmpfs
          o: size=100m,uid=1000
          type: tmpfs
        type: object
      Scope:
        description: 'The level at which the volume exists. Either `global` for cluster-wide,

          or `local` for machine level.'
        enum:
        - local
        - global
        example: local
        type: string
      Status:
        additionalProperties: {}
        description: 'Low-level details about the volume, provided by the volume driver.

          Details are returned as a map with key/value pairs:

          `{"key":"value","key2":"value2"}`.


          The `Status` field is optional, and is omitted if the volume driver

          does not support this feature.'
        example:
          hello: world
        type: object
      UsageData:
        $ref: '#/definitions/UsageData'
    required:
    - Driver
    - Labels
    - Mountpoint
    - Name
    - Options
    - Scope
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  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
  TypeMount:
    description: 'TypeMount contains options for using a volume as a Mount-type

      volume.'
    properties:
      FsType:
        description: FsType specifies the filesystem type for the mount volume. Optional.
        type: string
      MountFlags:
        description: MountFlags defines flags to pass when mounting the volume. Optional.
        items:
          type: string
        type: array
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  PublishStatus:
    description: 'PublishStatus represents the status of the volume as published to an

      individual node'
    properties:
      NodeID:
        description: NodeID is the ID of the swarm node this Volume is published to.
        type: string
      PublishContext:
        additionalProperties:
          type: string
        description: 'PublishContext is the PublishContext returned by the CSI plugin when

          a volume is published.'
        type: object
      State:
        $ref: '#/definitions/PublishState'
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  volumeCreate:
    description: Details for creating a volume
    properties:
      Driver:
        description: Name of the volume driver to use.
        type: string
      DriverOpts:
        additionalProperties:
          type: string
        description: 'A mapping of driver options and values. These options are

          passed directly to the driver and are driver specific.'
        type: object
      Labels:
        additionalProperties:
          type: string
        description: User-defined key/value metadata.
        type: object
      Name:
        description: The new volume's name. If not specified, Docker generates a name.
        type: string
    required:
    - Driver
    - DriverOpts
    - Labels
    - Name
    type: object
    x-go-package: go.podman.io/podman/v6/pkg/api/handlers/swagger
  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
  SharingMode:
    description: 'SharingMode defines the Sharing of a Cluster Volume. This is how Tasks using a

      Volume at the same time can use it.'
    type: string
    x-go-package: github.com/moby/moby/api/types/volume
  Topology:
    description: 'This description is taken verbatim from the CSI Spec:


      A topological domain is a sub-division of a cluster, like "region",

      "zone", "rack", etc.

      A topological segment is a specific instance of a topological domain,

      like "zone3", "rack3", etc.

      For example {"com.company/zone": "Z1", "com.company/rack": "R3"}

      Valid keys have two segments: an OPTIONAL prefix and name, separated'
    example: '"com.company.example/zone".'
    properties:
      Segments:
        additionalProperties:
          type: string
        type: object
    title: Topology is a map of topological domains to topological segments.
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  AccessMode:
    properties:
      BlockVolume:
        $ref: '#/definitions/TypeBlock'
      MountVolume:
        $ref: '#/definitions/TypeMount'
      Scope:
        $ref: '#/definitions/Scope'
      Sharing:
        $ref: '#/definitions/SharingMode'
    title: AccessMode defines the access mode of a volume.
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  Info:
    description: 'Info contains information about the Volume as a whole as provided by

      the CSI storage plugin.'
    properties:
      AccessibleTopology:
        description: 'AccessibleTopology is the topology this volume is actually accessible

          from.'
        items:
          $ref: '#/definitions/Topology'
        type: array
      CapacityBytes:
        description: 'CapacityBytes is the capacity of the volume in bytes. A value of 0

          indicates that the capacity is unknown.'
        format: int64
        type: integer
      VolumeContext:
        additionalProperties:
          type: string
        description: 'VolumeContext is the context originating from the CSI storage plugin

          when the Volume is created.'
        type: object
      VolumeID:
        description: 'VolumeID is the ID of the Volume as seen by the CSI storage plugin. This

          is distinct from the Volume''s Swarm ID, which is the ID used by all of

          the Docker Engine to refer to the Volume. If this field is blank, then

          the Volume has not been successfully created yet.'
        type: string
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  ClusterVolume:
    description: 'ClusterVolume contains options and information specific to, and only present

      on, Swarm CSI cluster volumes.'
    properties:
      CreatedAt:
        format: date-time
        type: string
      ID:
        description: 'ID is the Swarm ID of the volume. Because cluster volumes are Swarm

          objects, they have an ID, unlike non-cluster volumes, which only have a

          Name. This ID can be used to refer to the cluster volume.'
        type: string
      Info:
        $ref: '#/definitions/Info'
      PublishStatus:
        description: 'PublishStatus contains the status of the volume as it pertains to its

          publishing on Nodes.'
        items:
          $ref: '#/definitions/PublishStatus'
        type: array
      Spec:
        $ref: '#/definitions/ClusterVolumeSpec'
      UpdatedAt:
        format: date-time
        type: string
      Version:
        $ref: '#/definitions/Version'
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  PruneReport:
    description: POST "/volumes/prune"
    properties:
      Err:
        type: string
        x-go-type: error
      Id:
        type: string
      Size:
        format: uint64
        type: integer
    title: 'PruneReport contains the response for Engine API:'
    type: object
    x-go-package: go.podman.io/podman/v6/pkg/domain/entities/reports
  TopologyRequirement:
    description: 'TopologyRequirement expresses the user''s requirements for a volume''s

      accessible topology.'
    properties:
      Preferred:
        description: 'Preferred is a list of Topologies that the volume should attempt to be

          provisioned in.


          Taken from the CSI spec:


          Specifies the list of topologies the CO would prefer the volume to

          be provisioned in.


          This field is OPTIONAL. If TopologyRequirement is specified either

          requisite or preferred or both MUST be specified.


          An SP MUST attempt to make the provisioned volume available using

          the preferred topologies in order from first to last.


          If requisite is specified, all topologies in preferred list MUST

          also be present in the list of requisite topologies.


          If the SP is unable to make the provisioned volume available

          from any of the preferred topologies, the SP MAY choose a topology

          from the list of requisite topologies.

          If the list of requisite topologies is not specified, then the SP

          MAY choose from the list of all possible topologies.

          If the list of requisite topologies is specified and the SP is

          unable to make the provisioned volume available from any of the

          requisite topologies it MUST fail the CreateVolume call.


          Example 1:

          Given a volume should be accessible from a single zone, and

          requisite =

          {"region": "R1", "zone": "Z2"},

          {"region": "R1", "zone": "Z3"}

          preferred =

          {"region": "R1", "zone": "Z3"}

          then the SP SHOULD first attempt to make the provisioned volume

          available from "zone" "Z3" in the "region" "R1" and fall back to

          "zone" "Z2" in the "region" "R1" if that is not possible.


          Example 2:

          Given a volume should be accessible from a single zone, and

          requisite =

          {"region": "R1", "zone": "Z2"},

          {"region": "R1", "zone": "Z3"},

          {"region": "R1", "zone": "Z4"},

          {"region": "R1", "zone": "Z5"}

          preferred =

          {"region": "R1", "zone": "Z4"},

          {"region": "R1", "zone": "Z2"}

          then the SP SHOULD first attempt to make the provisioned volume

          accessible from "zone" "Z4" in the "region" "R1" and fall back to

          "zone" "Z2" in the "region" "R1" if that is not possible. If that

          is not possible, the SP may choose between either the "zone"

          "Z3" or "Z5" in the "region" "R1".


          Example 3:

          Given a volume should be accessible from TWO zones (because an

          opaque parameter in CreateVolumeRequest, for example, specifies

          the volume is accessible from two zones, aka synchronously

          replicated), and

          requisite =

          {"region": "R1", "zone": "Z2"},

          {"region": "R1", "zone": "Z3"},

          {"region": "R1", "zone": "Z4"},

          {"region": "R1", "zone": "Z5"}

          preferred =

          {"region": "R1", "zone": "Z5"},

          {"region": "R1", "zone": "Z3"}

          then the SP SHOULD first attempt to make the provisioned volume

          accessible from the combination of the two "zones" "Z5" and "Z3" in

          the "region" "R1". If that''s not possible, it should fall back to

          a combination of "Z5" and other possibilities from the list of

          requisite. If that''s not possible, it should fall back  to a

          combination of "Z3" and other possibilities from the list of

          requisite. If that''s not possible, it should fall back  to a

          combination of other possibilities from the list of requisite.'
        items:
          $ref: '#/definitions/Topology'
        type: array
      Requisite:
        description: 'Requisite specifies a list of Topologies, at least one of which the

          volume must be accessible from.


          Taken verbatim from the CSI Spec:


          Specifies the list of topologies the provisioned volume MUST be

          accessible from.

          This field is OPTIONAL. If TopologyRequirement is specified either

          requisite or preferred or both MUST be specified.


          If requisite is specified, the provisioned volume MUST be

          accessible from at least one of the requisite topologies.


          Given

          x = number of topologies provisioned volume is accessible from

          n = number of requisite topologies

          The CO MUST ensure n >= 1. The SP MUST ensure x >= 1

          If x==n, then the SP MUST make the provisioned volume available to

          all topologies from the list of requisite topologies. If it is

          unable to do so, the SP MUST fail the CreateVolume call.

          For example, if a volume should be accessible from a single zone,

          and requisite =

          {"region": "R1", "zone": "Z2"}

          then the provisioned volume MUST be accessible from the "region"

          "R1" and the "zone" "Z2".

          Similarly, if a volume should be accessible from two zones, and

          requisite =

          {"region": "R1", "zone": "Z2"},

          {"region": "R1", "zone": "Z3"}

          then the provisioned volume MUST be accessible from the "region"

          "R1" and both "zone" "Z2" and "zone" "Z3".


          If x<n, then the SP SHALL choose x unique topologies from the list

          of requisite topologies. If it is unable to do so, the SP MUST fail

          the CreateVolume call.

          For example, if a volume should be accessible from a single zone,

          and requisite =

          {"region": "R1", "zone": "Z2"},

          {"region": "R1", "zone": "Z3"}

          then the SP may choose to make the provisioned volume available in

          either the "zone" "Z2" or the "zone" "Z3" in the "region" "R1".

          Similarly, if a volume should be accessible from two zones, and

          requisite =

          {"region": "R1", "zone": "Z2"},

          {"region": "R1", "zone": "Z3"},

          {"region": "R1", "zone": "Z4"}

          then the provisioned volume MUST be accessible from any combination

          of two unique topologies: e.g. "R1/Z2" and "R1/Z3", or "R1/Z2" and

          "R1/Z4", or "R1/Z3" and "R1/Z4".


          If x>n, then the SP MUST make the provisioned volume available from

          all topologies from the list of requisite topologies and MAY choose

          the remaining x-n unique topologies from the list of all possible

          topologies. If it is unable to do so, the SP MUST fail the

          CreateVolume call.

          For example, if a volume should be accessible from two zones, and

          requisite =

          {"region": "R1", "zone": "Z2"}

          then the provisioned volume MUST be accessible from the "region"

          "R1" and the "zone" "Z2" and the SP may select the second zone

          independently, e.g. "R1/Z4".'
        items:
          $ref: '#/definitions/Topology'
        type: array
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  ListResponse:
    description: '# Volume list response'
    properties:
      Volumes:
        description: List of volumes
        items:
          $ref: '#/definitions/Volume'
        type: array
      Warnings:
        description: Warnings that occurred when fetching the list of volumes.
        example: []
        items:
          type: string
        type: array
    title: ListResponse VolumeListResponse
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  ClusterVolumeSpec:
    properties:
      AccessMode:
        $ref: '#/definitions/AccessMode'
      AccessibilityRequirements:
        $ref: '#/definitions/TopologyRequirement'
      Availability:
        $ref: '#/definitions/Availability'
      CapacityRange:
        $ref: '#/definitions/CapacityRange'
      Group:
        description: 'Group defines the volume group of this volume. Volumes belonging to the

          same group can be referred to by group name when creating Services.

          Referring to a volume by group instructs swarm to treat volumes in that

          group interchangeably for the purpose of scheduling. Volumes with an

          empty string for a group technically all belong to the same, emptystring

          group.'
        type: string
      Secrets:
        description: 'Secrets defines Swarm Secrets that are passed to the CSI storage plugin

          when operating on this volume.'
        items:
          $ref: '#/definitions/Secret'
        type: array
    title: ClusterVolumeSpec contains the spec used to create this volume.
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  UsageData:
    description: 'UsageData Usage details about the volume. This information is used by the

      `GET /system/df` endpoint, and omitted in other endpoints.'
    properties:
      RefCount:
        description: 'The number of containers referencing this volume. This field

          is set to `-1` if the reference-count is not available.'
        format: int64
        type: integer
      Size:
        description: 'Amount of disk space used by the volume (in bytes). This information

          is only available for volumes created with the `"local"` volume

          driver. For volumes created with other volume drivers, this field

          is set to `-1` ("not available")'
        format: int64
        type: integer
    required:
    - RefCount
    - Size
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  PublishState:
    description: 'PublishState represents the state of a Volume as it pertains to its

      use on a particular Node.'
    type: string
    x-go-package: github.com/moby/moby/api/types/volume
  Secret:
    properties:
      GID:
        format: uint32
        type: integer
      Mode:
        format: uint32
        type: integer
      Source:
        type: string
      Target:
        type: string
      UID:
        format: uint32
        type: integer
    type: object
    x-go-package: go.podman.io/podman/v6/pkg/specgen
  CapacityRange:
    description: 'CapacityRange describes the minimum and maximum capacity a volume should be

      created with'
    properties:
      LimitBytes:
        description: 'LimitBytes specifies that a volume must not be bigger than this. The

          value of 0 indicates an unspecified maximum'
        format: int64
        type: integer
      RequiredBytes:
        description: 'RequiredBytes specifies that a volume must be at least this big. The

          value of 0 indicates an unspecified minimum.'
        format: int64
        type: integer
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
  TypeBlock:
    description: Intentionally empty.
    title: TypeBlock defines options for using a volume as a block-type volume.
    type: object
    x-go-package: github.com/moby/moby/api/types/volume
responses:
  volumeInspect:
    description: This response definition is used for both the create and inspect endpoints
    schema:
      $ref: '#/definitions/Volume'
  internalError:
    description: Internal server error
    schema:
      $ref: '#/definitions/ErrorModel'
  volumeList:
    description: Volume List
    schema:
      $ref: '#/definitions/ListResponse'
  volumeNotFound:
    description: No such volume
    schema:
      $ref: '#/definitions/ErrorModel'
  volumePruneResponse:
    description: Volume prune
    schema:
      $ref: '#/definitions/PruneReport'