OpenAPI Specification
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 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
name: volumes
paths:
/libpod/volumes/{name}:
delete:
operationId: VolumeDeleteLibpod
parameters:
- description: the name or ID of the volume
in: path
name: name
required: true
type: string
- description: force removal
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
/libpod/volumes/{name}/exists:
get:
description: Check if a volume exists
operationId: VolumeExistsLibpod
parameters:
- description: the name of the volume
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'204':
description: volume exists
'404':
$ref: '#/responses/volumeNotFound'
'500':
$ref: '#/responses/internalError'
summary: Volume exists
tags:
- volumes
/libpod/volumes/{name}/export:
get:
operationId: VolumeExportLibpod
parameters:
- description: the name or ID of the volume
in: path
name: name
required: true
type: string
produces:
- application/x-tar
responses:
'200':
description: no error
schema:
format: binary
type: string
'404':
$ref: '#/responses/volumeNotFound'
'500':
$ref: '#/responses/internalError'
summary: Export a volume
tags:
- volumes
/libpod/volumes/{name}/import:
post:
operationId: VolumeImportLibpod
parameters:
- description: the name or ID of the volume
in: path
name: name
required: true
type: string
- description: 'An uncompressed tar archive
'
in: body
name: inputStream
schema:
format: binary
type: string
produces:
- application/json
responses:
'204':
description: Successful import
'404':
$ref: '#/responses/volumeNotFound'
'500':
$ref: '#/responses/internalError'
summary: Populate a volume by importing provided tar
tags:
- volumes
/libpod/volumes/{name}/json:
get:
operationId: VolumeInspectLibpod
parameters:
- description: the name or ID of the volume
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/volumeCreateResponse'
'404':
$ref: '#/responses/volumeNotFound'
'500':
$ref: '#/responses/internalError'
summary: Inspect volume
tags:
- volumes
/libpod/volumes/create:
post:
operationId: VolumeCreateLibpod
parameters:
- description: attributes for creating a volume
in: body
name: create
schema:
$ref: '#/definitions/VolumeCreateOptions'
produces:
- application/json
responses:
'201':
$ref: '#/responses/volumeCreateResponse'
'500':
$ref: '#/responses/internalError'
summary: Create a volume
tags:
- volumes
/libpod/volumes/json:
get:
description: Returns a list of volumes
operationId: VolumeListLibpod
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 - opt=<driver-option> Matches a storage driver options\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"
in: query
name: filters
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/volumeListLibpod'
'500':
$ref: '#/responses/internalError'
summary: List volumes
tags:
- volumes
/libpod/volumes/prune:
post:
operationId: VolumePruneLibpod
parameters:
- description: "JSON encoded value of filters (a map[string][]string) to match volumes against before pruning.\nAvailable filters:\n - `all` When true, prune all unused volumes; when false or unset, only anonymous unused volumes.\n - `anonymous` When true/false, restrict to anonymous or named volumes only.\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/volumePruneLibpod'
'500':
$ref: '#/responses/internalError'
summary: Prune volumes
tags:
- volumes
definitions:
VolumeConfigResponse:
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities
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
VolumeCreateOptions:
properties:
Driver:
description: Volume driver to use
type: string
GID:
description: GID that the volume will be created as
format: int64
type: integer
IgnoreIfExists:
description: Ignore existing volumes
type: boolean
Label:
additionalProperties:
type: string
description: User-defined key/value metadata. Provided for compatibility
type: object
Labels:
additionalProperties:
type: string
description: User-defined key/value metadata. Preferred field, will override Label
type: object
Name:
description: New volume's name. Can be left blank
type: string
Options:
additionalProperties:
type: string
description: Mapping of driver options and values.
type: object
UID:
description: UID that the volume will be created as
format: int64
type: integer
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities/types
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
responses:
volumePruneLibpod:
description: Volume Prune
schema:
items:
$ref: '#/definitions/PruneReport'
type: array
volumeNotFound:
description: No such volume
schema:
$ref: '#/definitions/ErrorModel'
internalError:
description: Internal server error
schema:
$ref: '#/definitions/ErrorModel'
volumeListLibpod:
description: Volume list
schema:
items:
$ref: '#/definitions/VolumeConfigResponse'
type: array
volumeCreateResponse:
description: Volume details
schema:
$ref: '#/definitions/VolumeConfigResponse'