zot API Command Reference¶

This article describes the zot REST API commands, parameters, and responses.

The information presented here is adapted from the interactive OpenAPI (formerly swagger) JSON file in the zot Github project.

For instructions and examples of how to use the zot API, see Using the zot API.

Note: zot also provides a GraphQL API for enhanced search capabilities. For details on using GraphQL queries, see Using GraphQL for Enhanced Searches.

/zot/auth/apikey¶

DELETE `/zot/auth/apikey`¶

Revokes one current user API key based on given key ID

Parameters

Name	In	Type	Required	Description
id	query	string	true	api token id (UUID)

Example responses

200 Response

"string"

Responses

Status	Meaning	Description	Schema
200	OK	ok	string
400	Bad Request	bad request	string
401	Unauthorized	unauthorized	string
500	Internal Server Error	internal server error	string

This operation does not require authentication

GET `/zot/auth/apikey`¶

Get list of all API keys for a logged in user

Example responses

200 Response

"string"

Responses

Status	Meaning	Description	Schema
200	OK	ok	string
401	Unauthorized	unauthorized	string
500	Internal Server Error	internal server error	string

This operation does not require authentication

POST `/zot/auth/apikey`¶

Can create an api key for a logged in user, based on the provided label and scopes.

Body parameter

{
  "expirationDate": "string",
  "label": "string",
  "scopes": [
    "string"
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	api.APIKeyPayload	true	api token id (UUID)

Example responses

201 Response

"string"

Responses

Status	Meaning	Description	Schema
201	Created	created	string
400	Bad Request	bad request	string
401	Unauthorized	unauthorized	string
500	Internal Server Error	internal server error	string

This operation does not require authentication

`/zot/auth/logout`¶

POST `/zot/auth/logout`¶

Logout by removing current session

Example responses

200 Response

"string"

Responses

Status	Meaning	Description	Schema
200	OK	ok".	string
500	Internal Server Error	internal server error".	string

This operation does not require authentication

`/oras/artifacts/v1/{name}/manifests/{digest}/referrers`¶

GET `/oras/artifacts/v1/{name}/manifests/{digest}/referrers`¶

Get references for an image given a digest and artifact type

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
digest	path	string	true	image digest
artifactType	query	string	true	artifact type

Example responses

200 Response

"string"

Responses

Status	Meaning	Description	Schema
200	OK	ok	string
404	Not Found	not found	string
500	Internal Server Error	internal server error	string

This operation does not require authentication

`/v2/`¶

GET `/v2/`¶

Check if this API version is supported

Example responses

200 Response

"string"

Responses

Status	Meaning	Description	Schema
200	OK	ok".	string

This operation does not require authentication

`/v2/_catalog`¶

GET `/v2/_catalog`¶

List all image repositories

Example responses

200 Response

{
  "repositories": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	api.RepositoryList
500	Internal Server Error	internal server error	string

This operation does not require authentication

`/v2/_oci/ext/discover`¶

GET `/v2/_oci/ext/discover`¶

List all extensions present on registry

Example responses

200 Response

{
  "extensions": [
    {
      "description": "string",
      "endpoints": [
        "string"
      ],
      "name": "string",
      "url": "string"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	api.ExtensionList

This operation does not require authentication

`/v2/_zot/ext/cosign`¶

POST `/v2/_zot/ext/cosign`¶

Upload cosign public keys for verifying signatures

Body parameter

string

Parameters

Name	In	Type	Required	Description
body	body	string	true	Public key content

Example responses

200 Response

"string"

Responses

Status	Meaning	Description	Schema
200	OK	ok	string
400	Bad Request	bad request".	string
500	Internal Server Error	internal server error".	string

This operation does not require authentication

`/v2/_zot/ext/mgmt`¶

GET `/v2/_zot/ext/mgmt`¶

Get current server configuration

Parameters

Name	In	Type	Required	Description
resource	query	string	false	specify resource

Enumerated Values

Parameter	Value
resource	config

Example responses

200 Response

{
  "binaryType": "string",
  "distSpecVersion": "string",
  "http": {
    "auth": {
      "allowAnonymousAccess": true,
      "bearer": {
        "realm": "string",
        "service": "string"
      },
      "htpasswd": {
        "path": "string"
      },
      "ldap": {
        "address": "string"
      },
      "openid": {
        "providers": {
          "property1": {
            "name": "string"
          },
          "property2": {
            "name": "string"
          }
        }
      }
    }
  }
}

http.auth.allowAnonymousAccess is derived from the access-control policy and is true when at least one repository rule defines an anonymousPolicy. It is response metadata for clients such as the zot UI, not a configuration attribute.

Responses

Status	Meaning	Description	Schema
200	OK	OK	extensions.StrippedConfig
500	Internal Server Error	internal server error".	string

This operation does not require authentication

`/v2/_zot/ext/notation`¶

POST `/v2/_zot/ext/notation`¶

Upload notation certificates for verifying signatures

Body parameter

string

Parameters

Name	In	Type	Required	Description
truststoreType	query	string	false	truststore type
body	body	string	true	Certificate content

Example responses

200 Response

"string"

Responses

Status	Meaning	Description	Schema
200	OK	ok	string
400	Bad Request	bad request".	string
500	Internal Server Error	internal server error".	string

This operation does not require authentication

`/v2/_zot/ext/userprefs`¶

PUT `/v2/_zot/ext/userprefs`¶

Add bookmarks/stars info

Parameters

Name	In	Type	Required	Description
action	query	string	true	specify action
repo	query	string	true	repository name

Enumerated Values

Parameter	Value
action	toggleBookmark
action	toggleStar

Example responses

200 Response

"string"

Responses

Status	Meaning	Description	Schema
200	OK	ok	string
400	Bad Request	bad request".	string
403	Forbidden	forbidden	string
404	Not Found	not found	string
500	Internal Server Error	internal server error	string

This operation does not require authentication

`/v2/{name}/blobs/{digest}`¶

DELETE `/v2/{name}/blobs/{digest}`¶

Delete an image's blob/layer given a digest

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
digest	path	string	true	blob/layer digest

Example responses

202 Response

"string"

Responses

Status	Meaning	Description	Schema
202	Accepted	accepted	string

This operation does not require authentication

GET `/v2/{name}/blobs/{digest}`¶

Get an image's blob/layer given a digest

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
digest	path	string	true	blob/layer digest

Example responses

200 Response

Responses

Status	Meaning	Description	Schema
200	OK	OK	api.ImageManifest

This operation does not require authentication

HEAD `/v2/{name}/blobs/{digest}`¶

Check an image's blob/layer given a digest

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
digest	path	string	true	blob/layer digest

Example responses

200 Response

{
  "annotations": {
    "property1": "string",
    "property2": "string"
  },
  "artifactType": "string",
  "config": {
    "annotations": {
      "property1": "string",
      "property2": "string"
    },
    "artifactType": "string",
    "data": [
      0
    ],
    "digest": "string",
    "mediaType": "string",
    "platform": {
      "architecture": "string",
      "os": "string",
      "os.features": [
        "string"
      ],
      "os.version": "string",
      "variant": "string"
    },
    "size": 0,
    "urls": [
      "string"
    ]
  },
  "layers": [
    {
      "annotations": {
        "property1": "string",
        "property2": "string"
      },
      "artifactType": "string",
      "data": [
        0
      ],
      "digest": "string",
      "mediaType": "string",
      "platform": {
        "architecture": "string",
        "os": "string",
        "os.features": [
          "string"
        ],
        "os.version": "string",
        "variant": "string"
      },
      "size": 0,
      "urls": [
        "string"
      ]
    }
  ],
  "mediaType": "string",
  "schemaVersion": 0,
  "subject": {
    "annotations": {
      "property1": "string",
      "property2": "string"
    },
    "artifactType": "string",
    "data": [
      0
    ],
    "digest": "string",
    "mediaType": "string",
    "platform": {
      "architecture": "string",
      "os": "string",
      "os.features": [
        "string"
      ],
      "os.version": "string",
      "variant": "string"
    },
    "size": 0,
    "urls": [
      "string"
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	api.ImageManifest

Response Headers

Status	Header	Type	Format	Description
200	constants.DistContentDigestKey	object		none

This operation does not require authentication

`/v2/{name}/blobs/uploads`¶

POST `/v2/{name}/blobs/uploads`¶

Create a new image blob/layer upload

Beginning with v2.1.23, the optional digest-algorithm query parameter provides an algorithm hint for a multi-request upload, for example POST /v2/example/blobs/uploads/?digest-algorithm=sha512. It must name an available digest algorithm. Empty, repeated, or unsupported values return 400 DIGEST_INVALID. For a monolithic upload supplying digest, the algorithm hint must match that digest's algorithm. The final upload PUT still supplies the complete digest.

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
digest-algorithm	query	string	false	digest algorithm hint for a multi-request upload

Example responses

202 Response

"string"

Responses

Status	Meaning	Description	Schema
202	Accepted	accepted	string
401	Unauthorized	unauthorized	string
404	Not Found	not found	string
500	Internal Server Error	internal server error	string

Response Headers

Status	Header	Type	Format	Description
202	Location	string		/v2/{name}/blobs/uploads/{session_id}
202	Range	string		0-0

This operation does not require authentication

`/v2/{name}/blobs/uploads/{session_id}`¶

DELETE `/v2/{name}/blobs/uploads/{session_id}`¶

Delete an image's blob/layer given a digest

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
session_id	path	string	true	upload session_id

Example responses

200 Response

"string"

Responses

Status	Meaning	Description	Schema
200	OK	ok	string
404	Not Found	not found	string
500	Internal Server Error	internal server error	string

This operation does not require authentication

GET `/v2/{name}/blobs/uploads/{session_id}`¶

*Get an image's blob/layer upload given a session_id

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
session_id	path	string	true	upload session_id

Example responses

204 Response

"string"

Responses

Status	Meaning	Description	Schema
204	No Content	no content	string
404	Not Found	not found	string
500	Internal Server Error	internal server error	string

This operation does not require authentication

PATCH `/v2/{name}/blobs/uploads/{session_id}`¶

Resume an image's blob/layer upload given an session_id

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
session_id	path	string	true	upload session_id

Example responses

202 Response

"string"

Responses

Status	Meaning	Description	Schema
202	Accepted	accepted	string
400	Bad Request	bad request	string
404	Not Found	not found	string
416	Range Not Satisfiable	range not satisfiable	string
500	Internal Server Error	internal server error	string

Response Headers

Status	Header	Type	Format	Description
202	Location	string		/v2/{name}/blobs/uploads/{session_id}
202	Range	string		0-128

This operation does not require authentication

PUT `/v2/{name}/blobs/uploads/{session_id}`¶

Update and finish an image's blob/layer upload given a digest

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
session_id	path	string	true	upload session_id
digest	query	string	true	blob/layer digest

Example responses

201 Response

"string"

Responses

Status	Meaning	Description	Schema
201	Created	created	string
404	Not Found	not found	string
500	Internal Server Error	internal server error	string

This operation does not require authentication

`/v2/{name}/manifests/{reference}`¶

DELETE `/v2/{name}/manifests/{reference}`¶

Delete an image's manifest given a reference or a digest

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
reference	path	string	true	image reference or digest

Example responses

200 Response

"string"

Responses

Status	Meaning	Description	Schema
200	OK	ok	string

This operation does not require authentication

GET `/v2/{name}/manifests/{reference}`¶

Get an image's manifest given a reference or a digest

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
reference	path	string	true	image reference or digest

Example responses

200 Response

{
  "annotations": {
    "property1": "string",
    "property2": "string"
  },
  "artifactType": "string",
  "config": {
    "annotations": {
      "property1": "string",
      "property2": "string"
    },
    "artifactType": "string",
    "data": [
      0
    ],
    "digest": "string",
    "mediaType": "string",
    "platform": {
      "architecture": "string",
      "os": "string",
      "os.features": [
        "string"
      ],
      "os.version": "string",
      "variant": "string"
    },
    "size": 0,
    "urls": [
      "string"
    ]
  },
  "layers": [
    {
      "annotations": {
        "property1": "string",
        "property2": "string"
      },
      "artifactType": "string",
      "data": [
        0
      ],
      "digest": "string",
      "mediaType": "string",
      "platform": {
        "architecture": "string",
        "os": "string",
        "os.features": [
          "string"
        ],
        "os.version": "string",
        "variant": "string"
      },
      "size": 0,
      "urls": [
        "string"
      ]
    }
  ],
  "mediaType": "string",
  "schemaVersion": 0,
  "subject": {
    "annotations": {
      "property1": "string",
      "property2": "string"
    },
    "artifactType": "string",
    "data": [
      0
    ],
    "digest": "string",
    "mediaType": "string",
    "platform": {
      "architecture": "string",
      "os": "string",
      "os.features": [
        "string"
      ],
      "os.version": "string",
      "variant": "string"
    },
    "size20": 0,
    "urls": [
      "string"
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	api.ImageManifest
404	Not Found	not found	string
500	Internal Server Error	internal server error	string

Response Headers

Status	Header	Type	Format	Description
200	constants.DistContentDigestKey	object		none

This operation does not require authentication

HEAD `/v2/{name}/manifests/{reference}`¶

Check an image's manifest given a reference or a digest

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
reference	path	string	true	image reference or digest

Example responses

200 Response

"string"

Responses

Status	Meaning	Description	Schema
200	OK	ok	string
404	Not Found	not found	string
500	Internal Server Error	internal server error".	string

Response Headers

Status	Header	Type	Format	Description
200	constants.DistContentDigestKey	object		none

This operation does not require authentication

PUT `/v2/{name}/manifests/{reference}`¶

Update an image's manifest given a reference or a digest

When a repository quota is exceeded, a push returns 413 with a DENIED error. For maxRepoBytes, the error detail contains the current size, projected size, and configured limit as byte-count strings. Byte-quota accounting failures return 503 when accounting is unavailable or 500 when stored size metadata is invalid. See Repository quotas.

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
reference	path	string	true	image reference or digest

Example responses

201 Response

"string"

Responses

Status	Meaning	Description	Schema
201	Created	created	string
400	Bad Request	bad request	string
404	Not Found	not found	string
413	Content Too Large	repository quota exceeded	DENIED error
500	Internal Server Error	internal server error	string
503	Service Unavailable	byte-quota accounting unavailable	DENIED error

This operation does not require authentication

`/v2/{name}/referrers/{digest}`¶

GET `/v2/{name}/referrers/{digest}`¶

Get referrers given a digest

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
digest	path	string	true	digest
artifactType	query	string	false	artifact type

Example responses

200 Response

{
  "annotations": {
    "property1": "string",
    "property2": "string"
  },
  "artifactType": "string",
  "manifests": [
    {
      "annotations": {
        "property1": "string",
        "property2": "string"
      },
      "artifactType": "string",
      "data": [
        0
      ],
      "digest": "string",
      "mediaType": "string",
      "platform": {
        "architecture": "string",
        "os": "string",
        "os.features": [
          "string"
        ],
        "os.version": "string",
        "variant": "string"
      },
      "size": 0,
      "urls": [
        "string"
      ]
    }
  ],
  "mediaType": "string",
  "schemaVersion": 0,
  "subject": {
    "annotations": {
      "property1": "string",
      "property2": "string"
    },
    "artifactType": "string",
    "data": [
      0
    ],
    "digest": "string",
    "mediaType": "string",
    "platform": {
      "architecture": "string",
      "os": "string",
      "os.features": [
        "string"
      ],
      "os.version": "string",
      "variant": "string"
    },
    "size": 0,
    "urls": [
      "string"
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	api.ImageIndex
404	Not Found	not found	string
500	Internal Server Error	internal server error	string

This operation does not require authentication

`/v2/{name}/tags/list`¶

GET `/v2/{name}/tags/list`¶

List all image tags in a repository

Parameters

Name	In	Type	Required	Description
name	path	string	true	repository name
n	query	integer	true	limit entries for pagination
last	query	string	true	last tag value for pagination

Example responses

200 Response

{
  "name": "string",
  "tags": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	common.ImageTags
400	Bad Request	bad request".	string
404	Not Found	not found	string

This operation does not require authentication

zot API Command Reference¶

/zot/auth/apikey¶

DELETE /zot/auth/apikey¶

GET /zot/auth/apikey¶

POST /zot/auth/apikey¶

/zot/auth/logout¶

POST /zot/auth/logout¶

/oras/artifacts/v1/{name}/manifests/{digest}/referrers¶

GET /oras/artifacts/v1/{name}/manifests/{digest}/referrers¶

/v2/¶

GET /v2/¶

/v2/_catalog¶

GET /v2/_catalog¶

/v2/_oci/ext/discover¶

GET /v2/_oci/ext/discover¶

/v2/_zot/ext/cosign¶

POST /v2/_zot/ext/cosign¶

/v2/_zot/ext/mgmt¶

GET /v2/_zot/ext/mgmt¶

/v2/_zot/ext/notation¶

POST /v2/_zot/ext/notation¶

/v2/_zot/ext/userprefs¶

PUT /v2/_zot/ext/userprefs¶

/v2/{name}/blobs/{digest}¶

DELETE /v2/{name}/blobs/{digest}¶

GET /v2/{name}/blobs/{digest}¶

HEAD /v2/{name}/blobs/{digest}¶

/v2/{name}/blobs/uploads¶

POST /v2/{name}/blobs/uploads¶

/v2/{name}/blobs/uploads/{session_id}¶

DELETE /v2/{name}/blobs/uploads/{session_id}¶

GET /v2/{name}/blobs/uploads/{session_id}¶

PATCH /v2/{name}/blobs/uploads/{session_id}¶

PUT /v2/{name}/blobs/uploads/{session_id}¶

/v2/{name}/manifests/{reference}¶

DELETE /v2/{name}/manifests/{reference}¶

GET /v2/{name}/manifests/{reference}¶

HEAD /v2/{name}/manifests/{reference}¶

PUT /v2/{name}/manifests/{reference}¶

/v2/{name}/referrers/{digest}¶

GET /v2/{name}/referrers/{digest}¶

/v2/{name}/tags/list¶

GET /v2/{name}/tags/list¶

DELETE `/zot/auth/apikey`¶

GET `/zot/auth/apikey`¶

POST `/zot/auth/apikey`¶

`/zot/auth/logout`¶

POST `/zot/auth/logout`¶

`/oras/artifacts/v1/{name}/manifests/{digest}/referrers`¶

GET `/oras/artifacts/v1/{name}/manifests/{digest}/referrers`¶

`/v2/`¶

GET `/v2/`¶

`/v2/_catalog`¶

GET `/v2/_catalog`¶

`/v2/_oci/ext/discover`¶

GET `/v2/_oci/ext/discover`¶

`/v2/_zot/ext/cosign`¶

POST `/v2/_zot/ext/cosign`¶

`/v2/_zot/ext/mgmt`¶

GET `/v2/_zot/ext/mgmt`¶

`/v2/_zot/ext/notation`¶

POST `/v2/_zot/ext/notation`¶

`/v2/_zot/ext/userprefs`¶

PUT `/v2/_zot/ext/userprefs`¶

`/v2/{name}/blobs/{digest}`¶

DELETE `/v2/{name}/blobs/{digest}`¶

GET `/v2/{name}/blobs/{digest}`¶

HEAD `/v2/{name}/blobs/{digest}`¶

`/v2/{name}/blobs/uploads`¶

POST `/v2/{name}/blobs/uploads`¶

`/v2/{name}/blobs/uploads/{session_id}`¶

DELETE `/v2/{name}/blobs/uploads/{session_id}`¶

GET `/v2/{name}/blobs/uploads/{session_id}`¶

PATCH `/v2/{name}/blobs/uploads/{session_id}`¶

PUT `/v2/{name}/blobs/uploads/{session_id}`¶

`/v2/{name}/manifests/{reference}`¶

DELETE `/v2/{name}/manifests/{reference}`¶

GET `/v2/{name}/manifests/{reference}`¶

HEAD `/v2/{name}/manifests/{reference}`¶

PUT `/v2/{name}/manifests/{reference}`¶

`/v2/{name}/referrers/{digest}`¶

GET `/v2/{name}/referrers/{digest}`¶

`/v2/{name}/tags/list`¶

GET `/v2/{name}/tags/list`¶