Podman

Podman Artifacts API

Actions related to artifacts

GitHub OpenAPI

Operations 9

DELETE /libpod/artifacts/{name} Remove an artifact #
GET /libpod/artifacts/{name}/extract Extract an artifacts contents #
GET /libpod/artifacts/{name}/json Inspect an artifact #
POST /libpod/artifacts/{name}/push Push an artifact #
POST /libpod/artifacts/add Add a file as an artifact #
GET /libpod/artifacts/json List artifacts #
POST /libpod/artifacts/local/add Add a local file as an artifact #
POST /libpod/artifacts/pull Pull an artifact #
DELETE /libpod/artifacts/remove Remove one or more artifacts #

Documentation

📖
Documentation
https://docs.podman.io/en/latest/_static/api.html
📖
GettingStarted
https://docs.podman.io/en/latest/markdown/podman-system-service.1.html

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/podman/refs/heads/main/openapi/podman-artifacts-api-openapi.yml

Other Resources

🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/podman/refs/heads/main/apis.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/podman-artifacts-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

podman-artifacts-api-openapi.yml Raw ↑ 
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.
  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 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 artifacts
  name: Artifacts
paths:
  /libpod/artifacts/{name}:
    delete:
      description: Remove a single artifact from local storage by name or ID.
      operationId: ArtifactDeleteLibpod
      parameters:
      - description: Name or ID of the artifact to remove
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/artifactRemoveResponse'
        '404':
          $ref: '#/components/responses/artifactNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Remove an artifact
      tags:
      - Artifacts
  /libpod/artifacts/{name}/extract:
    get:
      description: Extract the files of an OCI artifact to the local filesystem as a tar archive.
      operationId: ArtifactExtractLibpod
      parameters:
      - description: Name or digest of the artifact
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Only extract the file with the given title
        in: query
        name: title
        schema:
          type: string
      - description: Only extract the file with the given digest
        in: query
        name: digest
        schema:
          type: string
      - description: 'When extracting a single file from an artifact, don''t use the files title as the file name in the tar archive

          '
        in: query
        name: excludeTitle
        schema:
          type: boolean
      responses:
        '200':
          description: Extract successful
          content:
            application/x-tar:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/artifactNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Extract an artifacts contents
      tags:
      - Artifacts
  /libpod/artifacts/{name}/json:
    get:
      description: Retrieve detailed information about a specific OCI artifact by name or ID.
      operationId: ArtifactInspectLibpod
      parameters:
      - description: Name or ID of the artifact
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/inspectArtifactResponse'
        '404':
          $ref: '#/components/responses/artifactNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Inspect an artifact
      tags:
      - Artifacts
  /libpod/artifacts/{name}/push:
    post:
      description: Push an OCI artifact from local storage to a remote image registry.
      operationId: ArtifactPushLibpod
      parameters:
      - description: Mandatory reference to the artifact (e.g., quay.io/image/artifact:tag)
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Number of times to retry in case of failure when performing pull
        in: query
        name: retry
        schema:
          type: integer
          default: 3
      - description: Delay between retries in case of pull failures (e.g., 10s)
        in: query
        name: retryDelay
        schema:
          type: string
          default: 1s
      - description: Require TLS verification
        in: query
        name: tlsVerify
        schema:
          type: boolean
          default: true
      - description: 'base-64 encoded auth config.

          Must include the following four values: username, password, email and server address

          OR simply just an identity token.

          '
        in: header
        name: X-Registry-Auth
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/artifactPushResponse'
        '400':
          $ref: '#/components/responses/badParamError'
        '401':
          $ref: '#/components/responses/artifactBadAuth'
        '404':
          $ref: '#/components/responses/artifactNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Push an artifact
      tags:
      - Artifacts
  /libpod/artifacts/add:
    post:
      description: Add a file as a new OCI artifact, or append to an existing artifact if 'append' is true.
      operationId: ArtifactAddLibpod
      parameters:
      - description: Mandatory reference to the artifact (e.g., quay.io/image/artifact:tag)
        in: query
        name: name
        required: true
        schema:
          type: string
      - description: Path of the file to be added
        in: query
        name: fileName
        required: true
        schema:
          type: string
      - description: Optionally set the type of file
        in: query
        name: fileMIMEType
        schema:
          type: string
      - description: Array of annotation strings e.g "test=true"
        in: query
        name: annotations
        schema:
          type: array
          items:
            type: string
      - description: Use type to describe an artifact
        in: query
        name: artifactMIMEType
        schema:
          type: string
      - description: Append files to an existing artifact
        in: query
        name: append
        schema:
          type: boolean
          default: false
      - description: Replace an existing artifact with the same name
        in: query
        name: replace
        schema:
          type: boolean
          default: false
      responses:
        '201':
          $ref: '#/components/responses/artifactAddResponse'
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/artifactNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Add a file as an artifact
      tags:
      - Artifacts
      requestBody:
        content:
          application/octet-stream:
            schema:
              format: binary
              type: string
        description: Binary stream of the file to add to an artifact
  /libpod/artifacts/json:
    get:
      description: Return a list of all OCI artifacts in local storage.
      operationId: ArtifactListLibpod
      responses:
        '200':
          $ref: '#/components/responses/artifactListResponse'
        '500':
          $ref: '#/components/responses/internalError'
      summary: List artifacts
      tags:
      - Artifacts
  /libpod/artifacts/local/add:
    post:
      description: Add a file from the local filesystem as a new OCI artifact, or append to an existing artifact if 'append' is true.
      operationId: ArtifactLocalLibpod
      parameters:
      - description: Mandatory reference to the artifact (e.g., quay.io/image/artifact:tag)
        in: query
        name: name
        required: true
        schema:
          type: string
      - description: Absolute path to the local file on the server filesystem to be added
        in: query
        name: path
        required: true
        schema:
          type: string
      - description: Name/title of the file within the artifact
        in: query
        name: fileName
        required: true
        schema:
          type: string
      - description: Optionally set the MIME type of the file
        in: query
        name: fileMIMEType
        schema:
          type: string
      - description: Array of annotation strings e.g "test=true"
        in: query
        name: annotations
        schema:
          type: array
          items:
            type: string
      - description: Use type to describe an artifact
        in: query
        name: artifactMIMEType
        schema:
          type: string
      - description: Append files to an existing artifact
        in: query
        name: append
        schema:
          type: boolean
          default: false
      - description: Replace an existing artifact with the same name
        in: query
        name: replace
        schema:
          type: boolean
          default: false
      responses:
        '201':
          $ref: '#/components/responses/artifactAddResponse'
        '400':
          $ref: '#/components/responses/badParamError'
        '404':
          $ref: '#/components/responses/artifactNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Add a local file as an artifact
      tags:
      - Artifacts
  /libpod/artifacts/pull:
    post:
      description: Pull an OCI artifact from a remote registry to local storage.
      operationId: ArtifactPullLibpod
      parameters:
      - description: Mandatory reference to the artifact (e.g., quay.io/image/artifact:tag)
        in: query
        name: name
        required: true
        schema:
          type: string
      - description: Number of times to retry in case of failure when performing pull
        in: query
        name: retry
        schema:
          type: integer
          default: 3
      - description: Delay between retries in case of pull failures (e.g., 10s)
        in: query
        name: retryDelay
        schema:
          type: string
          default: 1s
      - description: Require TLS verification
        in: query
        name: tlsVerify
        schema:
          type: boolean
          default: true
      - description: 'base-64 encoded auth config.

          Must include the following four values: username, password, email and server address

          OR simply just an identity token.

          '
        in: header
        name: X-Registry-Auth
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/artifactPullResponse'
        '400':
          $ref: '#/components/responses/badParamError'
        '401':
          $ref: '#/components/responses/artifactBadAuth'
        '404':
          $ref: '#/components/responses/artifactNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Pull an artifact
      tags:
      - Artifacts
  /libpod/artifacts/remove:
    delete:
      description: 'Remove one or more OCI artifacts from local storage.

        Can be filtered by name/ID or all artifacts can be removed.'
      operationId: ArtifactDeleteAllLibpod
      parameters:
      - description: List of artifact names/IDs to remove
        in: query
        name: artifacts
        schema:
          type: array
          items:
            type: string
      - description: Remove all artifacts
        in: query
        name: all
        schema:
          type: boolean
      - description: Ignore errors if artifact does not exist
        in: query
        name: ignore
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/artifactRemoveResponse'
        '404':
          $ref: '#/components/responses/artifactNotFound'
        '500':
          $ref: '#/components/responses/internalError'
      summary: Remove one or more artifacts
      tags:
      - Artifacts
components:
  responses:
    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'
    artifactPullResponse:
      description: Artifact Pull
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ArtifactPullReport'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/ArtifactPullReport'
        text/plain:
          schema:
            $ref: '#/components/schemas/ArtifactPullReport'
    artifactPushResponse:
      description: Artifact Push
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ArtifactPushReport'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/ArtifactPushReport'
        text/plain:
          schema:
            $ref: '#/components/schemas/ArtifactPushReport'
    artifactBadAuth:
      description: error in authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/ErrorModel'
        text/plain:
          schema:
            $ref: '#/components/schemas/ErrorModel'
    inspectArtifactResponse:
      description: Inspect Artifact
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ArtifactInspectReport'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/ArtifactInspectReport'
        text/plain:
          schema:
            $ref: '#/components/schemas/ArtifactInspectReport'
    artifactRemoveResponse:
      description: Artifact Remove
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ArtifactRemoveReport'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/ArtifactRemoveReport'
        text/plain:
          schema:
            $ref: '#/components/schemas/ArtifactRemoveReport'
    artifactNotFound:
      description: No such artifact
      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'
    artifactListResponse:
      description: Artifact list
      content:
        application/json:
          schema:
            items:
              $ref: '#/components/schemas/ArtifactListReport'
            type: array
        application/octet-stream:
          schema:
            items:
              $ref: '#/components/schemas/ArtifactListReport'
            type: array
        text/plain:
          schema:
            items:
              $ref: '#/components/schemas/ArtifactListReport'
            type: array
    artifactAddResponse:
      description: Artifact Add
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ArtifactAddReport'
        application/octet-stream:
          schema:
            $ref: '#/components/schemas/ArtifactAddReport'
        text/plain:
          schema:
            $ref: '#/components/schemas/ArtifactAddReport'
  schemas:
    ArtifactAddReport:
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities
    ArtifactRemoveReport:
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities
    ArtifactInspectReport:
      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
    ArtifactPushReport:
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities
    ArtifactListReport:
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities
    ArtifactPullReport:
      type: object
      x-go-package: go.podman.io/podman/v6/pkg/domain/entities