Using the zot API¶

This document describes how to use the zot REST API and provides a number of examples.

For comprehensive details of all zot API commands, see Viewing the complete zot API reference.

The zot API implements the OCI Distribution endpoints along with additional endpoints for supported extensions. You can access the REST API at the same URL and port number used by the GUI and by datapath tools.

The examples in this article assume that the zot registry is located at localhost:8080.

Supported API endpoints¶

The following is a list of zot API endpoints along with the conditions under which each endpoint is available.

Some API endpoints are available only when a specific extension is enabled in the zot configuration file, or when an extension build label is specified in the make command (for example, make binary EXTENSIONS=ui), or both.

For comprehensive details of the API endpoints, see Viewing the complete zot API reference.

OCI endpoints¶

zot OCI extension endpoints¶

zot auth endpoints¶

other zot endpoints¶

ORAS endpoints¶

prometheus endpoint¶

OpenAPI (swagger) endpoints¶

This endpoint is accessed with a browser.

API authentication¶

If zot authentication is not configured, any user can access the zot API.

When pushing and pulling images using API calls, your identity can be authenticated by either a password or an API key.

With a valid password, you can specify your credentials in a cURL request as shown in this example:

curl -u <user>:<password> -X GET http://<server>/<endpoint>

An API key has advantages in situations where the primary zot authentication does not use the command line, such as a GUI login or social login. Also, you can reduce your security exposure by using an API key instead of your broader credentials, such as an LDAP username and password.

Using API keys¶

Enabling API keys¶

To enable the use of API keys, you must set the apikey attribute to true in the zot configuration file, as shown in the following example:

  "http": {
    "auth": {
      "apikey": true
    }
  }

Creating your API key¶

Before you can create or revoke an API key, you must first log in using a different authentication mechanism, such as logging in through the zot GUI. When you are logged in, you can create an API key for your identity using the following API command:

POST /zot/auth/apikey

cURL command example:

curl -u user:password -X POST http://localhost:8080/zot/auth/apikey -d '{"label": "myAPIKEY", "scopes": ["repo1", "repo2"], "expirationDate": "2023-08-28T17:10:05+03:00"}'

The scopes and expiration date in this example are optional. By default, an API key has the same permissions as the user who created it.

Command output:

{
  "createdAt":"2023-08-28T17:09:59.2603515+03:00",
  "expirationDate":"2023-08-28T17:10:05+03:00",
  "isExpired":false,
  "creatorUa":"curl/7.68.0",
  "generatedBy":"manual",
  "lastUsed":"0001-01-01T00:00:00Z",
  "label":"myAPIKEY",
  "scopes": [
    "repo1",
    "repo2"
  ],
  "uuid":"c931e635-a80d-4b52-b035-6b57be5f6e74",
  "apiKey":"zak_ac55a8693d6b4370a2003fa9e10b3682"
}

The API key (apiKey) is shown to the user only in the command output when the key is created. It cannot be later retrieved from zot with any other command.

Using your API key in an API command¶

The API key replaces a password in the API command, as shown in the following cURL example:

curl -u user:zak_e77bcb9e9f634f1581756abbf9ecd269 http://localhost:8080/v2/_catalog

Removing your API key¶

When logged in, you can revoke your own API key with the following API command:

DELETE /zot/auth/apikey?id=$uuid

cURL command example:

curl -u user:password -X DELETE http://localhost:8080/v2/zot/auth/apikey?id=46a45ce7-5d92-498a-a9cb-9654b1da3da1

Listing your current API keys¶

When logged in, you can display a list of your API keys with the following API command:

GET /zot/auth/apikey

cURL command example:

curl -u user:password -X GET http://localhost:8080/zot/auth/apikey

Command output:

{
  "apiKeys": [
    {
      "createdAt": "2023-05-05T15:39:28.420926+03:00",
      "expirationDate": "0001-01-01T00:00:00Z",
      "isExpired": true,
      "creatorUa": "curl/7.68.0",
      "generatedBy": "manual",
      "lastUsed": "0001-01-01T00:00:00Z",
      "label": "git",
      "scopes": [
        "repo1",
        "repo2"
      ],
      "uuid": "46a45ce7-5d92-498a-a9cb-9654b1da3da1"
    },
    {
      "createdAt": "2023-08-11T14:43:00.6459729+03:00",
      "expirationDate": "2023-08-17T18:24:05+03:00",
      "isExpired": false,
      "creatorUa": "curl/7.68.0",
      "generatedBy": "manual",
      "lastUsed": "2023-08-11T14:43:47.5559998+03:00",
      "label": "myAPIKEY",
      "scopes": null,
      "uuid": "294abf69-b62f-4e58-b214-dad2aec0bc52"
    }
  ]
}

This command output example shows an expired key and a current key for this user.

The actual API key (apiKey) is not shown. The key is shown to the user only when it is created.

API examples¶

The following examples assume that the zot registry is located at localhost:8080.

Listing repositories¶

To get a list of all image repositories in the registry, use the following API endpoint:

GET /v2/_catalog

cURL command example:

curl -X GET http://localhost:8080/v2/_catalog

Command output:

{
    "repositories": ["alpine", "busybox"]
}

Discovering extension endpoints¶

To list the installed and enabled zot extensions that can be accessed through the API, use the following OCI API endpoint:

GET /v2/_oci/ext/discover

cURL command example:

curl -X GET http://localhost:8080/v2/_oci/ext/discover

Command output:

{
  "extensions": [
  {
    "name": "_zot",
    "url": "https://github.com/project-zot/zot/blob//pkg/extensions/_zot.md",
    "description": "zot registry extensions",
    "endpoints": ["/v2/_zot/ext/search", "/v2/_zot/ext/userprefs", "/v2/_zot/ext/mgmt"]
  }]
}

Uploading a certificate for Notation¶

To upload a certificate for notation, use the following endpoint:

POST /v2/_zot/ext/notation

cURL command example:

curl --data-binary @certificate.crt -X POST "http://localhost:8080/v2/_zot/ext/notation?truststoreType=ca"

Viewing the complete zot API reference¶

You can find comprehensive details of all zot API commands in either of the following locations:

• As text descriptions in the zot API Command Reference in the zot documentation.

• As an interactive OpenAPI (swagger) JSON file in the zot Github project.

There are many ways to view a swagger file as an interactive document. If you have the npm package installed, for example, you can execute the following command:

  $ npx open-swagger-ui swagger.json

This command creates a local web server at localhost:3355 where you can interact with the API reference using a browser.