Project Quay API Guide

The Project Quay application programming interface (API) is an OAuth 2 RESTful API that consists of a set of endpoints for adding, displaying, changing and deleting features for Project Quay.

Project Quay abides by the Semantic Versioning (SemVer) specifications. The following conditions are met with each major, minor, and patch release:

Major versions of Project Quay might include incompatible API changes. For example, the API of Project Quay 2.0 differs from Project Quay 3.0.
Minor versions of Project Quay, for example, 3.y, adds functionality in a backwards compatible manner.
Patch versions of Project Quay, for example, 3.y.z, introduces backwards compatible bug fixes.

Currently, Project Quay uses the api/v1 endpoint for 3.y.z releases.

This guide describes the api/v1 endpoints and the browser-based examples for accessing those endpoints.

Using the Project Quay API

Project Quay provides a full OAuth 2, RESTful API that:

Is available from endpoints of each Project Quay instance from the URL https://<yourquayhost>/api/v1
Lets you connect to endpoints, via a browser, to get, delete, post, and put Project Quay settings by enabling the Swagger UI
Can be accessed by applications that make API calls and use OAuth tokens
Sends and receives data as JSON

The following text describes how to access the Project Quay API and use it to view and modify setting in your Project Quay cluster. The next section lists and describes API endpoints.

Accessing the Quay API from Quay.io

If you don’t have your own Project Quay cluster running yet, you can explore the Project Quay API available from Quay.io from your web browser:

https://docs.quay.io/api/swagger/

The API Explorer that appears shows Quay.io API endpoints. You will not see superuser API endpoints or endpoints for Project Quay features that are not enabled on Quay.io (such as Repository Mirroring).

From API Explorer, you can get, and sometimes change, information on:

Billing, subscriptions, and plans
Repository builds and build triggers
Error messages and global messages
Repository images, manifests, permissions, notifications, vulnerabilities, and image signing
Usage logs
Organizations, members and OAuth applications
User and robot accounts
and more…

Select to open an endpoint to view the Model Schema for each part of the endpoint. Open an endpoint, enter any required parameters (such as a repository name or image), then select the Try it out! button to query or change settings associated with a Quay.io endpoint.

Create OAuth access token

To create an OAuth access token so you can access the API for your organization:

Log in to Project Quay and select your Organization (or create a new one).
Select the Applications icon from the left navigation.
Select Create New Application and give the new application a name when prompted.
Select the new application.
Select Generate Token from the left navigation.
Select the checkboxes to set the scope of the token and select Generate Access Token.
Review the permissions you are allowing and select Authorize Application to approve it.
Copy the newly generated token to use to access the API.

Accessing your Quay API from a web browser

By enabling Swagger, you can access the API for your own Project Quay instance through a web browser. This URL exposes the Project Quay API explorer via the Swagger UI and this URL:

https://<yourquayhost>/api/v1/discovery.

That way of accessing the API does not include superuser endpoints that are available on Project Quay installations. Here is an example of accessing a Project Quay API interface running on the local system by running the swagger-ui container image:

# export SERVER_HOSTNAME=<yourhostname>
# sudo podman run -p 8888:8080 -e API_URL=https://$SERVER_HOSTNAME:8443/api/v1/discovery docker.io/swaggerapi/swagger-ui

With the swagger-ui container running, open your web browser to localhost port 8888 to view API endpoints via the swagger-ui container.

To avoid errors in the log such as "API calls must be invoked with an X-Requested-With header if called from a browser," add the following line to the config.yaml on all nodes in the cluster and restart Project Quay:

BROWSER_API_CALLS_XHR_ONLY: false

Accessing the Project Quay API from the command line

You can use the curl command to GET, PUT, POST, or DELETE settings via the API for your Project Quay cluster. Replace <token> with the OAuth access token you created earlier to get or change settings in the following examples.

Get superuser information

$ curl -X GET -H "Authorization: Bearer <token_here>" \
    "https://<yourquayhost>/api/v1/superuser/users/"

For example:

$ curl -X GET -H "Authorization: Bearer mFCdgS7SAIoMcnTsHCGx23vcNsTgziAa4CmmHIsg" http://quay-server:8080/api/v1/superuser/users/ | jq

{
  "users": [
    {
      "kind": "user",
      "name": "quayadmin",
      "username": "quayadmin",
      "email": "quayadmin@example.com",
      "verified": true,
      "avatar": {
        "name": "quayadmin",
        "hash": "357a20e8c56e69d6f9734d23ef9517e8",
        "color": "#5254a3",
        "kind": "user"
      },
      "super_user": true,
      "enabled": true
    }
  ]
}

Creating a superuser using the API

Configure a superuser name, as described in the Deploy Quay book:
- Use the configuration editor UI or
- Edit the config.yaml file directly, with the option of using the configuration API to validate (and download) the updated configuration bundle

Create the user account for the superuser name:

Obtain an authorization token as detailed above, and use curl to create the user:

$ curl -H "Content-Type: application/json"  -H "Authorization: Bearer Fava2kV9C92p1eXnMawBZx9vTqVnksvwNm0ckFKZ" -X POST --data '{
 "username": "quaysuper",
 "email": "quaysuper@example.com"
}'  http://quay-server:8080/api/v1/superuser/users/ | jq

The returned content includes a generated password for the new user account:

{
  "username": "quaysuper",
  "email": "quaysuper@example.com",
  "password": "EH67NB3Y6PTBED8H0HC6UVHGGGA3ODSE",
  "encrypted_password": "fn37AZAUQH0PTsU+vlO9lS0QxPW9A/boXL4ovZjIFtlUPrBz9i4j9UDOqMjuxQ/0HTfy38goKEpG8zYXVeQh3lOFzuOjSvKic2Vq7xdtQsU="
}

Now, when you request the list of users , it will show quaysuper as a superuser:

$ curl -X GET -H "Authorization: Bearer mFCdgS7SAIoMcnTsHCGx23vcNsTgziAa4CmmHIsg" http://quay-server:8080/api/v1/superuser/users/ | jq

{
  "users": [
  {
      "kind": "user",
      "name": "quayadmin",
      "username": "quayadmin",
      "email": "quayadmin@example.com",
      "verified": true,
      "avatar": {
        "name": "quayadmin",
        "hash": "357a20e8c56e69d6f9734d23ef9517e8",
        "color": "#5254a3",
        "kind": "user"
      },
      "super_user": true,
      "enabled": true
    },
    {
      "kind": "user",
      "name": "quaysuper",
      "username": "quaysuper",
      "email": "quaysuper@example.com",
      "verified": true,
      "avatar": {
        "name": "quaysuper",
        "hash": "c0e0f155afcef68e58a42243b153df08",
        "color": "#969696",
        "kind": "user"
      },
      "super_user": true,
      "enabled": true
    }
  ]
}

List usage logs

An intrnal API, /api/v1/superuser/logs, is available to list the usage logs for the current system. The results are paginated, so in the following example, more than 20 repos were created to show how to use multiple invocations to access the entire result set.

Example for pagination

First invocation

$ curl -X GET -k -H "Authorization: Bearer qz9NZ2Np1f55CSZ3RVOvxjeUdkzYuCp0pKggABCD" https://example-registry-quay-quay-enterprise.apps.example.com/api/v1/superuser/logs | jq

Initial output

{
  "start_time": "Sun, 12 Dec 2021 11:41:55 -0000",
  "end_time": "Tue, 14 Dec 2021 11:41:55 -0000",
  "logs": [
    {
      "kind": "create_repo",
      "metadata": {
        "repo": "t21",
        "namespace": "namespace1"
      },
      "ip": "10.131.0.13",
      "datetime": "Mon, 13 Dec 2021 11:41:16 -0000",
      "performer": {
        "kind": "user",
        "name": "user1",
        "is_robot": false,
        "avatar": {
          "name": "user1",
          "hash": "5d40b245471708144de9760f2f18113d75aa2488ec82e12435b9de34a6565f73",
          "color": "#ad494a",
          "kind": "user"
        }
      },
      "namespace": {
        "kind": "org",
        "name": "namespace1",
        "avatar": {
          "name": "namespace1",
          "hash": "6cf18b5c19217bfc6df0e7d788746ff7e8201a68cba333fca0437e42379b984f",
          "color": "#e377c2",
          "kind": "org"
        }
      }
    },
    {
      "kind": "create_repo",
      "metadata": {
        "repo": "t20",
        "namespace": "namespace1"
      },
      "ip": "10.131.0.13",
      "datetime": "Mon, 13 Dec 2021 11:41:05 -0000",
      "performer": {
        "kind": "user",
        "name": "user1",
        "is_robot": false,
        "avatar": {
          "name": "user1",
          "hash": "5d40b245471708144de9760f2f18113d75aa2488ec82e12435b9de34a6565f73",
          "color": "#ad494a",
          "kind": "user"
        }
      },
      "namespace": {
        "kind": "org",
        "name": "namespace1",
        "avatar": {
          "name": "namespace1",
          "hash": "6cf18b5c19217bfc6df0e7d788746ff7e8201a68cba333fca0437e42379b984f",
          "color": "#e377c2",
          "kind": "org"
        }
      }
    },
...

   {
      "kind": "create_repo",
      "metadata": {
        "repo": "t2",
        "namespace": "namespace1"
      },
      "ip": "10.131.0.13",
      "datetime": "Mon, 13 Dec 2021 11:25:17 -0000",
      "performer": {
        "kind": "user",
        "name": "user1",
        "is_robot": false,
        "avatar": {
          "name": "user1",
          "hash": "5d40b245471708144de9760f2f18113d75aa2488ec82e12435b9de34a6565f73",
          "color": "#ad494a",
          "kind": "user"
        }
      },
      "namespace": {
        "kind": "org",
        "name": "namespace1",
        "avatar": {
          "name": "namespace1",
          "hash": "6cf18b5c19217bfc6df0e7d788746ff7e8201a68cba333fca0437e42379b984f",
          "color": "#e377c2",
          "kind": "org"
        }
      }
    }
  ],
  "next_page": "gAAAAABhtzGDsH38x7pjWhD8MJq1_2FAgqUw2X9S2LoCLNPH65QJqB4XAU2qAxYb6QqtlcWj9eI6DUiMN_q3e3I0agCvB2VPQ8rY75WeaiUzM3rQlMc4i6ElR78t8oUxVfNp1RMPIRQYYZyXP9h6E8LZZhqTMs0S-SedaQJ3kVFtkxZqJwHVjgt23Ts2DonVoYwtKgI3bCC5"
}

Second invocation using next_page

$ curl -X GET -k -H "Authorization: Bearer qz9NZ2Np1f55CSZ3RVOvxjeUdkzYuCp0pKggABCD" https://example-registry-quay-quay-enterprise.apps.example.com/api/v1/superuser/logs?next_page=gAAAAABhtzGDsH38x7pjWhD8MJq1_2FAgqUw2X9S2LoCLNPH65QJqB4XAU2qAxYb6QqtlcWj9eI6DUiMN_q3e3I0agCvB2VPQ8rY75WeaiUzM3rQlMc4i6ElR78t8oUxVfNp1RMPIRQYYZyXP9h6E8LZZhqTMs0S-SedaQJ3kVFtkxZqJwHVjgt23Ts2DonVoYwtKgI3bCC5 | jq

Output from second invocation

{
  "start_time": "Sun, 12 Dec 2021 11:42:46 -0000",
  "end_time": "Tue, 14 Dec 2021 11:42:46 -0000",
  "logs": [
    {
      "kind": "create_repo",
      "metadata": {
        "repo": "t1",
        "namespace": "namespace1"
      },
      "ip": "10.131.0.13",
      "datetime": "Mon, 13 Dec 2021 11:25:07 -0000",
      "performer": {
        "kind": "user",
        "name": "user1",
        "is_robot": false,
        "avatar": {
          "name": "user1",
          "hash": "5d40b245471708144de9760f2f18113d75aa2488ec82e12435b9de34a6565f73",
          "color": "#ad494a",
          "kind": "user"
        }
      },
      "namespace": {
        "kind": "org",
        "name": "namespace1",
        "avatar": {
          "name": "namespace1",
          "hash": "6cf18b5c19217bfc6df0e7d788746ff7e8201a68cba333fca0437e42379b984f",
          "color": "#e377c2",
          "kind": "org"
        }
      }
    },
    ...
  ]
}

Directory synchronization

To enable directory synchronization for the team newteam in organization testadminorg, where the corresponding group name in LDAP is ldapgroup:

$ curl -X POST -H "Authorization: Bearer 9rJYBR3v3pXcj5XqIA2XX6Thkwk4gld4TCYLLWDF" \
       -H "Content-type: application/json" \
       -d '{"group_dn": "cn=ldapgroup,ou=Users"}' \
       http://quay1-server:8080/api/v1/organization/testadminorg/team/newteam/syncing

To disable synchronization for the same team:

$ curl -X DELETE -H "Authorization: Bearer 9rJYBR3v3pXcj5XqIA2XX6Thkwk4gld4TCYLLWDF" \
       http://quay1-server:8080/api/v1/organization/testadminorg/team/newteam/syncing

Create a repository build via API

In order to build a repository from the specified input and tag the build with custom tags, users can use requestRepoBuild endpoint. It takes the following data:

{
"docker_tags": [
   "string"
],
"pull_robot": "string",
"subdirectory": "string",
"archive_url": "string"
}

The archive_url parameter should point to a tar or zip archive that includes the Dockerfile and other required files for the build. The file_id parameter was apart of our older build system. It cannot be used anymore. If Dockerfile is in a sub-directory it needs to be specified as well.

The archive should be publicly accessible. OAuth app should have "Administer Organization" scope because only organization admins have access to the robots' account tokens. Otherwise, someone could get robot permissions by simply granting a build access to a robot (without having access themselves), and use it to grab the image contents. In case of errors, check the json block returned and ensure the archive location, pull robot, and other parameters are being passed correctly. Click "Download logs" on the top-right of the individual build’s page to check the logs for more verbose messaging.

Create an org robot

$ curl -X PUT https://quay.io/api/v1/organization/{orgname}/robots/{robot shortname} \
   -H 'Authorization: Bearer <token>''

Trigger a build

$ curl -X POST https://quay.io/api/v1/repository/YOURORGNAME/YOURREPONAME/build/ \
   -H 'Authorization: Bearer <token>'

Python with requests

import requests
r = requests.post('https://quay.io/api/v1/repository/example/example/image', headers={'content-type': 'application/json', 'Authorization': 'Bearer <redacted>'}, data={[<request-body-contents>})
print(r.text)

Create a private repository

$ curl -X POST https://quay.io/api/v1/repository \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{"namespace":"yournamespace", "repository":"yourreponame",
    "description":"descriptionofyourrepo", "visibility": "private"}' | jq

Create a mirrored repository

Minimal configuration

curl -X POST
  -H "Authorization: Bearer ${bearer_token}"
  -H "Content-Type: application/json"
  --data '{"external_reference": "quay.io/minio/mc", "external_registry_username": "", "sync_interval": 600, "sync_start_date": "2021-08-06T11:11:39Z", "root_rule": {"rule_kind": "tag_glob_csv", "rule_value": [ "latest" ]}, "robot_username": "orga+robot"}' https://${quay_registry}/api/v1/repository/${orga}/${repo}/mirror | jq

Extended configuration

$ curl -X POST
  -H "Authorization: Bearer ${bearer_token}"
  -H "Content-Type: application/json"
  --data '{"is_enabled": true, "external_reference": "quay.io/minio/mc", "external_registry_username": "username", "external_registry_password": "password", "external_registry_config": {"unsigned_images":true, "verify_tls": false, "proxy": {"http_proxy": "http://proxy.tld", "https_proxy": "https://proxy.tld", "no_proxy": "domain"}}, "sync_interval": 600, "sync_start_date": "2021-08-06T11:11:39Z", "root_rule": {"rule_kind": "tag_glob_csv", "rule_value": [ "*" ]}, "robot_username": "orga+robot"}' https://${quay_registry}/api/v1/repository/${orga}/${repo}/mirror | jq

Project Quay Application Programming Interface (API)

This API allows you to perform many of the operations required to work with Project Quay repositories, users, and organizations.

Authorization

oauth2_implicit

Scopes

The following scopes are used to control access to the API endpoints:

Scope	Description
repo:read	This application will be able to view and pull all repositories visible to the granting user or robot account
repo:write	This application will be able to view, push and pull to all repositories to which the granting user or robot account has write access
repo:admin	This application will have administrator access to all repositories to which the granting user or robot account has access
repo:create	This application will be able to create repositories in to any namespaces that the granting user or robot account is allowed to create repositories
user:read	This application will be able to read user information such as username and email address.
org:admin	This application will be able to administer your organizations including creating robots, creating teams, adjusting team membership, and changing billing settings. You should have absolute trust in the requesting application before granting this permission.
super:user	This application will be able to administer your installation including managing users, managing organizations and other features found in the superuser panel. You should have absolute trust in the requesting application before granting this permission.
user:admin	This application will be able to administer your account including creating robots and granting them permissions to your repositories. You should have absolute trust in the requesting application before granting this permission.

Scope

Description

repo:read

This application will be able to view and pull all repositories visible to the granting user or robot account

repo:write

This application will be able to view, push and pull to all repositories to which the granting user or robot account has write access

repo:admin

This application will have administrator access to all repositories to which the granting user or robot account has access

repo:create

This application will be able to create repositories in to any namespaces that the granting user or robot account is allowed to create repositories

user:read

This application will be able to read user information such as username and email address.

org:admin

This application will be able to administer your organizations including creating robots, creating teams, adjusting team membership, and changing billing settings. You should have absolute trust in the requesting application before granting this permission.

super:user

This application will be able to administer your installation including managing users, managing organizations and other features found in the superuser panel. You should have absolute trust in the requesting application before granting this permission.

user:admin

This application will be able to administer your account including creating robots and granting them permissions to your repositories. You should have absolute trust in the requesting application before granting this permission.

appspecifictokens

Manages app specific tokens for the current user.

createAppToken

Create a new app specific token for user.

POST /api/v1/user/apptoken

Authorizations: oauth2_implicit (user:admin)

Request body schema (application/json)

Description of a new token.

Name	Description	Schema
friendlyName optional	Friendly name to help identify the token	string

Name

Description

Schema

friendlyName
optional

Friendly name to help identify the token

string

Responses

HTTP Code	Description	Schema
201	Successful creation
400	Bad Request	ApiError
401	Session required	ApiError
403	Unauthorized access	ApiError
404	Not found	ApiError

HTTP Code

Description

Schema

201

Successful creation

400

Bad Request

Project Quay API Guide

Using the Project Quay API

Accessing the Quay API from Quay.io

Create OAuth access token

Accessing your Quay API from a web browser

Accessing the Project Quay API from the command line

Get superuser information

Creating a superuser using the API

List usage logs

Example for pagination

Directory synchronization

Create a repository build via API

Create an org robot

Trigger a build

Create a private repository

Create a mirrored repository

Project Quay Application Programming Interface (API)

Authorization

Scopes

appspecifictokens

createAppToken

POST /api/v1/user/apptoken

Request body schema (application/json)

Responses

listAppTokens

GET /api/v1/user/apptoken

Query parameters

Responses

getAppToken

GET /api/v1/user/apptoken/{token_uuid}

Path parameters

Responses

revokeAppToken

DELETE /api/v1/user/apptoken/{token_uuid}

Path parameters

Responses

build

getRepoBuildStatus

GET /api/v1/repository/{repository}/build/{build_uuid}/status

Path parameters

Responses

getRepoBuildLogs

GET /api/v1/repository/{repository}/build/{build_uuid}/logs

Path parameters

Responses

getRepoBuild

GET /api/v1/repository/{repository}/build/{build_uuid}

Path parameters

Responses

cancelRepoBuild

DELETE /api/v1/repository/{repository}/build/{build_uuid}

Path parameters

Responses

requestRepoBuild

POST /api/v1/repository/{repository}/build/

Path parameters

Request body schema (application/json)

Responses

getRepoBuilds

GET /api/v1/repository/{repository}/build/

Path parameters

Query parameters

Responses

discovery

discovery

GET /api/v1/discovery

Query parameters

Responses

error

getErrorDescription

GET /api/v1/error/{error_type}

Path parameters

Responses

globalmessages

createGlobalMessage

POST /api/v1/messages

Request body schema (application/json)

Responses

getGlobalMessages

GET /api/v1/messages