Podman manifests 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 Manifests 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 manifests
  name: manifests
paths:
  /libpod/manifests/{name}:
    delete:
      description: 'Delete named manifest list


        As of v4.0.0

        '
      operationId: ManifestDeleteLibpod
      parameters:
      - description: The name or ID of the  list to be deleted
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Ignore if a specified manifest does not exist and do not throw an error.
        in: query
        name: ignore
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/imagesRemoveResponseLibpod'
        '404':
          $ref: '#/components/responses/manifestNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Delete manifest list
      tags:
      - manifests
    post:
      description: Create a manifest list
      operationId: ManifestCreateLibpod
      parameters:
      - description: manifest list or index name to create
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: 'One or more names of an image or a manifest list. Repeat parameter as needed.


          Support for multiple images, as of version 4.0.0

          Alias of `image` is support for compatibility with < 4.0.0

          Response status code is 200 with < 4.0.0 for compatibility

          '
        in: query
        name: images
        required: true
        schema:
          type: string
      - description: add all contents if given list
        in: query
        name: all
        schema:
          type: boolean
      - description: modify an existing list if one with the desired name already exists
        in: query
        name: amend
        schema:
          type: boolean
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDResponse'
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/imageNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Create
      tags:
      - manifests
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManifestModifyOptions'
          application/x-tar:
            schema:
              $ref: '#/components/schemas/ManifestModifyOptions'
        description: options for new manifest
    put:
      description: 'Add/Remove an image(s) to a manifest list


        Note: operations are not atomic when multiple Images are provided.


        As of v4.0.0

        '
      operationId: ManifestModifyLibpod
      parameters:
      - description: the name or ID of the manifest
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Require HTTPS and verify signatures when contacting registries.
        in: query
        name: tlsVerify
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManifestModifyReport'
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/manifestNotFound'
        '409':
          description: Operation had partial success, both Images and Errors may have members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManifestModifyReport'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Modify manifest list
      tags:
      - manifests
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManifestModifyOptions'
          application/x-tar:
            schema:
              $ref: '#/components/schemas/ManifestModifyOptions'
        description: options for mutating a manifest
        required: true
  /libpod/manifests/{name}/add:
    post:
      description: 'Add an image to a manifest list


        Deprecated: As of 4.0.0 use ManifestModifyLibpod instead

        '
      operationId: ManifestAddLibpod
      parameters:
      - description: the name or ID of the manifest
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDResponse'
        '404':
          $ref: '#/components/responses/manifestNotFound'
        '409':
          $ref: '#/components/responses/badParamError'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Add image
      tags:
      - manifests
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManifestAddOptions'
          application/x-tar:
            schema:
              $ref: '#/components/schemas/ManifestAddOptions'
        description: options for creating a manifest
  /libpod/manifests/{name}/exists:
    get:
      description: 'Check if manifest list exists


        Note: There is no contract that the manifest list will exist for a follow-on operation

        '
      operationId: ManifestExistsLibpod
      parameters:
      - description: the name or ID of the manifest list
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: manifest list exists
        '404':
          $ref: '#/components/responses/manifestNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Exists
      tags:
      - manifests
  /libpod/manifests/{name}/json:
    get:
      description: Display attributes of given manifest list
      operationId: ManifestInspectLibpod
      parameters:
      - description: the name or ID of the manifest list
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Require HTTPS and verify signatures when contacting registries.
        in: query
        name: tlsVerify
        schema:
          type: boolean
          default: true
      responses:
        '200':
          $ref: '#/components/responses/manifestInspect'
        '404':
          $ref: '#/components/responses/manifestNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Inspect
      tags:
      - manifests
  /libpod/manifests/{name}/push:
    post:
      description: 'Push a manifest list or image index to a registry


        Deprecated: As of 4.0.0 use ManifestPushLibpod instead

        '
      operationId: ManifestPushV3Libpod
      parameters:
      - description: the name or ID of the manifest
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: the destination for the manifest
        in: query
        name: destination
        required: true
        schema:
          type: string
      - description: push all images
        in: query
        name: all
        schema:
          type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDResponse'
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/manifestNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Push manifest to registry
      tags:
      - manifests
  /libpod/manifests/{name}/registry/{destination}:
    post:
      description: 'Push a manifest list or image index to the named registry


        As of v4.0.0

        '
      operationId: ManifestPushLibpod
      parameters:
      - description: the name or ID of the manifest list
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: add existing instances with requested compression algorithms to manifest list
        in: query
        name: addCompression
        schema:
          type: array
          items:
            type: string
      - description: Enforce compressing the layers with the specified --compression and do not reuse differently compressed blobs on the registry.
        in: query
        name: forceCompressionFormat
        schema:
          type: boolean
          default: false
      - description: the registry for the manifest list
        in: path
        name: destination
        required: true
        schema:
          type: string
      - description: push all images
        in: query
        name: all
        schema:
          type: boolean
          default: true
      - description: Require HTTPS and verify signatures when contacting registries.
        in: query
        name: tlsVerify
        schema:
          type: boolean
          default: true
      - description: silences extra stream data on push
        in: query
        name: quiet
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDResponse'
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/manifestNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Push manifest list to registry
      tags:
      - manifests
components:
  schemas:
    Schema2List:
      title: Schema2List is a list of platform-specific manifests.
      type: object
      x-go-package: go.podman.io/image/v5/manifest
    ManifestModifyReport:
      properties:
        Id:
          description: Manifest List ID
          type: string
          x-go-name: ID
        errors:
          description: Errors associated with operation
          items:
            type: string
            x-go-type: error
          type: array
          x-go-name: Errors
        files:
          description: Files added to manifest list, otherwise not provided.
          items:
            type: string
          type: array
          x-go-name: Files
        images:
          description: Images added to or removed from manifest list, otherwise not provided.
          items:
            type: string
          type: array
          x-go-name: Images
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities/types
    ImageRemoveReport:
      description: 'ImageRemoveReport is the response for removing one or more image(s) from storage

        and images what was untagged vs actually removed.'
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities
    IDResponse:
      properties:
        Id:
          description: The id of the newly created object.
          type: string
          x-go-name: ID
      required:
      - Id
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities/types
    ManifestModifyOptions:
      description: 'swagger 2.0 does not support oneOf for schema validation.


        Operation "update" uses all fields.

        Operation "remove" uses fields: Operation and Images

        Operation "annotate" uses fields: Operation and Annotations'
      properties:
        all:
          description: True when operating on a list to include all images
          type: boolean
          x-go-name: All
        annotation:
          description: Annotation to add to the item in the manifest list
          items:
            type: string
          type: array
          x-go-name: Annotation
        annotations:
          additionalProperties:
            type: string
          description: Annotations to add to the item in the manifest list by a map which is preferred over Annotation
          type: object
          x-go-name: Annotations
        arch:
          description: Arch overrides the architecture for the item in the manifest list
          type: string
          x-go-name: Arch
        artifact_annotations:
          additionalProperties:
            type: string
          type: object
          x-go-name: ArtifactAnnotations
        artifact_config:
          type: string
          x-go-name: ArtifactConfig
        artifact_config_type:
          type: string
          x-go-name: ArtifactConfigType
        artifact_exclude_titles:
          type: boolean
          x-go-name: ArtifactExcludeTitles
        artifact_files:
          items:
            type: string
          type: array
          x-go-name: ArtifactFiles
        artifact_layer_type:
          type: string
          x-go-name: ArtifactLayerType
        artifact_subject:
          type: string
          x-go-name: ArtifactSubject
        artifact_type:
          description: 'The following are all of the fields from ManifestAddArtifactOptions.

            We can''t just embed the whole structure because it embeds a

            ManifestAnnotateOptions, which would conflict with the one that

            ManifestAddOptions embeds.'
          type: string
          x-go-name: ArtifactType
        features:
          description: Feature list for the item in the manifest list
          items:
            type: string
          type: array
          x-go-name: Features
        images:
          description: Images is an optional list of image references to add to manifest list
          items:
            type: string
          type: array
          x-go-name: Images
        index_annotation:
          description: IndexAnnotation is a slice of key=value annotations to add to the manifest list itself
          items:
            type: string
          type: array
          x-go-name: IndexAnnotation
        index_annotations:
          additionalProperties:
            type: string
          description: IndexAnnotations is a map of key:value annotations to add to the manifest list itself, by a map which is preferred over IndexAnnotation
          type: object
          x-go-name: IndexAnnotations
        operation:
          type: string
          x-go-name: Operation
        os:
          description: OS overrides the operating system for the item in the manifest list
          type: string
          x-go-name: OS
        os_features:
          description: OS features for the item in the manifest list
          items:
            type: string
          type: array
          x-go-name: OSFeatures
        os_version:
          description: OSVersion overrides the operating system for the item in the manifest list
          type: string
          x-go-name: OSVersion
        subject:
          description: IndexSubject is a subject value to set in the manifest list itself
          type: string
          x-go-name: IndexSubject
        variant:
          description: Variant for the item in the manifest list
          type: string
          x-go-name: Variant
      title: ManifestModifyOptions provides the model for mutating a manifest
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities
    LibpodImagesRemoveReport:
      allOf:
      - $ref: '#/components/schemas/ImageRemoveReport'
      - properties:
          Errors:
            description: Image removal requires is to return data and an error.
            items:
              type: string
            type: array
        type: object
      description: 'LibpodImagesRemoveReport is the return type for image removal via the rest

        api.'
      x-go-package: go.podman.io/podman/v6/pkg/api/handlers
    ManifestAddOptions:
      description: ManifestAddOptions provides model for adding digests to manifest list
      properties:
        all:
          description: True when operating on a list to include all images
          type: boolean
          x-go-name: All
        annotation:
          description: Annotation to add to the item in the manifest list
          items:
            type: string
          type: array
          x-go-name: Annotation
        annotations:
          additionalProperties:
            type: string
          description: Annotations to add to the item in the manifest list by a map which is preferred over Annotation
          type: object
          x-go-name: Annotations
        arch:
          description: Arch overrides the architecture for the item in the manifest list
          type: string
          x-go-name: Arch
        features:
          description: Feature list for the item in the manifest list
          items:
            type: string
          type: array
          x-go-name: Features
        images:
          description: Images is an optional list of image references to add to manifest list
          items:
            type: string
          type: array
          x-go-name: Images
        index_annotation:
          description: IndexAnnotation is a slice of key=value annotations to add to the manifest list itself
          items:
            type: string
          type: array
          x-go-name: IndexAnnotation
        index_annotations:
          additionalProperties:
            type: string
          description: IndexAnnotations is a map of key:value annotations to add to the manifest list itself, by a map which is preferred over IndexAnnotation
          type: object
          x-go-name: IndexAnnotations
        os:
          description: OS overrides the operating system for the item in the manifest list
          type: string
          x-go-name: OS
        os_features:
          description: OS features for the item in the manifest list
          items:
            type: string
          type: array
          x-go-name: OSFeatures
        os_version:
          description: OSVersion overrides the operating system for the item in the manifest list
          type: string
          x-go-name: OSVersion
        subject:
          description: IndexSubject is a subject value to set in the manifest list itself
          type: string
          x-go-name: IndexSubject
        variant:
          description: Variant for the item in the manifest list
          type: string
          x-go-name: Variant
      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
  responses:
    imagesRemoveResponseLibpod:
      description: Image Remove
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LibpodImagesRemoveReport'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/LibpodImagesRemoveReport'
        text/plain:
          schema:
            $ref: '#/components/schemas/LibpodImagesRemoveReport'
    manifestNotFound:
      description: No such manifest
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/ErrorModel'
        text/plain:
          schema:
            $ref: '#/components/schemas/ErrorModel'
    imageNotFound:
      description: No such image
      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'
    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'
    manifestInspect:
      description: Inspect Manifest
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Schema2List'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/Schema2List'
        text/plain:
          schema:
            $ref: '#/components/schemas/Schema2List'