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 secrets 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 secrets
name: secrets
paths:
/libpod/secrets/{name}:
delete:
operationId: SecretDeleteLibpod
parameters:
- description: the name or ID of the secret
in: path
name: name
required: true
type: string
- default: false
description: Remove all secrets
in: query
name: all
type: boolean
produces:
- application/json
responses:
'204':
description: no error
'404':
$ref: '#/responses/NoSuchSecret'
'500':
$ref: '#/responses/internalError'
summary: Remove secret
tags:
- secrets
/libpod/secrets/{name}/exists:
get:
operationId: SecretExistsLibpod
parameters:
- description: the name or ID of the secret
in: path
name: name
required: true
type: string
produces:
- application/json
responses:
'204':
description: secret exists
'404':
$ref: '#/responses/NoSuchSecret'
'500':
$ref: '#/responses/internalError'
summary: Secret exists
tags:
- secrets
/libpod/secrets/{name}/json:
get:
operationId: SecretInspectLibpod
parameters:
- description: the name or ID of the secret
in: path
name: name
required: true
type: string
- default: false
description: Display Secret
in: query
name: showsecret
type: boolean
produces:
- application/json
responses:
'200':
$ref: '#/responses/SecretInspectResponse'
'404':
$ref: '#/responses/NoSuchSecret'
'500':
$ref: '#/responses/internalError'
summary: Inspect secret
tags:
- secrets
/libpod/secrets/create:
post:
operationId: SecretCreateLibpod
parameters:
- description: User-defined name of the secret.
in: query
name: name
required: true
type: string
- default: file
description: Secret driver
in: query
name: driver
type: string
- description: JSON-encoded string containing secret driver options as a `map[string]string`.
in: query
name: driveropts
type: string
- description: JSON-encoded string containing labels as a `map[string]string`.
in: query
name: labels
type: string
- default: false
description: Replace an existing secret with the same name.
in: query
name: replace
type: boolean
- default: false
description: Ignore the request if a secret with the same name already exists.
in: query
name: ignore
type: boolean
- description: Secret
in: body
name: request
schema:
type: string
produces:
- application/json
responses:
'201':
$ref: '#/responses/SecretCreateResponse'
'500':
$ref: '#/responses/internalError'
summary: Create a secret
tags:
- secrets
/libpod/secrets/json:
get:
description: Returns a list of secrets
operationId: SecretListLibpod
parameters:
- description: "JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list. Currently available filters:\n - `name=[name]` Matches secrets name (accepts regex).\n - `id=[id]` Matches for full or partial ID.\n"
in: query
name: filters
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/SecretListResponse'
'500':
$ref: '#/responses/internalError'
summary: List secrets
tags:
- secrets
definitions:
SecretInfoReport:
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
SecretCreateReport:
type: object
x-go-package: go.podman.io/podman/v6/pkg/domain/entities
responses:
NoSuchSecret:
description: No such secret
schema:
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
SecretCreateResponse:
description: Secret create response
schema:
allOf:
- $ref: '#/definitions/SecretCreateReport'
SecretInspectResponse:
description: Secret inspect response
schema:
$ref: '#/definitions/SecretInfoReport'
SecretListResponse:
description: Secret list response
schema:
items:
$ref: '#/definitions/SecretInfoReport'
type: array
internalError:
description: Internal server error
schema:
$ref: '#/definitions/ErrorModel'