Chapter 15. Using the Red Hat Quay API Red Hat Quay provides a full OAuth 2 , RESTful API that: Is available from endpoints of each Red Hat Quay instance from the URL https://<yourquayhost>/api/v1 Lets you connect to endpoints, via a browser, to get, delete, post, and put Red Hat 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 Red Hat Quay API and use it to view and modify setting in your Red Hat Quay cluster. The section lists and describes API endpoints. 15.1. Accessing the Quay API from Quay.io If you don't have your own Red Hat Quay cluster running yet, you can explore the Red Hat Quay API available from Quay.io from your web browser: The API Explorer that appears shows Quay.io API endpoints. You will not see superuser API endpoints or endpoints for Red Hat 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. 15.2. Creating an OAuth access token OAuth access tokens are credentials that allow you to access protected resources in a secure manner. With Red Hat Quay, you must create an OAuth access token before you can access the API endpoints of your organization. Use the following procedure to create an OAuth access token. Prerequisites You have logged in to Red Hat Quay as an administrator. Procedure On the main page, select an Organization. In the navigation pane, select Applications . Click Create New Application and provide a new application name, then press Enter . On the OAuth Applications page, select the name of your application. Optional. Enter the following information: Application Name Homepage URL Description Avatar E-mail Redirect/Callback URL prefix In the navigation pane, select Generate Token . Check the boxes for the following options: Administer Organization Administer Repositories Create Repositories View all visible repositories Read/Write to any accessible repositories Super User Access Administer User Read User Information Click Generate Access Token . You are redirected to a new page. Review the permissions that you are allowing, then click Authorize Application . Confirm your decision by clicking Authorize Application . You are redirected to the Access Token page. Copy and save the access token. Important This is the only opportunity to copy and save the access token. It cannot be reobtained after leaving this page. 15.3. Accessing your Quay API from a web browser By enabling Swagger, you can access the API for your own Red Hat Quay instance through a web browser. This URL exposes the Red Hat Quay API explorer via the Swagger UI and this URL: That way of accessing the API does not include superuser endpoints that are available on Red Hat Quay installations. Here is an example of accessing a Red Hat Quay API interface running on the local system by running the swagger-ui container image: 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 Red Hat Quay: 15.4. Accessing the Red Hat Quay API from the command line You can use the curl command to GET, PUT, POST, or DELETE settings via the API for your Red Hat Quay cluster. Replace <token> with the OAuth access token you created earlier to get or change settings in the following examples. 15.4.1. Get superuser information For example: USD 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 } ] } 15.4.2. 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: 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: USD 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 } ] } 15.4.3. 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. 15.4.3.1. Example for pagination First invocation USD 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 USD 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" } } }, ... ] } 15.4.4. Directory synchronization To enable directory synchronization for the team newteam in organization testadminorg , where the corresponding group name in LDAP is ldapgroup : To disable synchronization for the same team: 15.4.5. 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: 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. 15.4.6. Create an org robot 15.4.7. Trigger a build Python with requests 15.4.8. Create a private repository 15.4.9. Create a mirrored repository Minimal configuration curl -X POST -H "Authorization: Bearer USD{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://USD{quay_registry}/api/v1/repository/USD{orga}/USD{repo}/mirror | jq Extended configuration USD curl -X POST -H "Authorization: Bearer USD{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://USD{quay_registry}/api/v1/repository/USD{orga}/USD{repo}/mirror | jq

Commands:
https://docs.quay.io/api/swagger/
https://<yourquayhost>/api/v1/discovery.
export SERVER_HOSTNAME=<yourhostname> sudo podman run -p 8888:8080 -e API_URL=https://USDSERVER_HOSTNAME:8443/api/v1/discovery docker.io/swaggerapi/swagger-ui
BROWSER_API_CALLS_XHR_ONLY: false
curl -X GET -H "Authorization: Bearer <token_here>" "https://<yourquayhost>/api/v1/superuser/users/"
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 } ] }
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
username: quaysuper
email: quaysuper@example.com
password: EH67NB3Y6PTBED8H0HC6UVHGGGA3ODSE
encrypted_password: fn37AZAUQH0PTsU+vlO9lS0QxPW9A/boXL4ovZjIFtlUPrBz9i4j9UDOqMjuxQ/0HTfy38goKEpG8zYXVeQh3lOFzuOjSvKic2Vq7xdtQsU=
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 } ] }
curl -X GET -k -H "Authorization: Bearer qz9NZ2Np1f55CSZ3RVOvxjeUdkzYuCp0pKggABCD" https://example-registry-quay-quay-enterprise.apps.example.com/api/v1/superuser/logs | jq
{ "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" }
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
{ "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" } } }, ] }
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
curl -X DELETE -H "Authorization: Bearer 9rJYBR3v3pXcj5XqIA2XX6Thkwk4gld4TCYLLWDF" http://quay1-server:8080/api/v1/organization/testadminorg/team/newteam/syncing
{ "docker_tags": [ "string" ], "pull_robot": "string", "subdirectory": "string", "archive_url": "string" }
curl -X PUT https://quay.io/api/v1/organization/{orgname}/robots/{robot shortname} -H 'Authorization: Bearer <token>''
curl -X POST https://quay.io/api/v1/repository/YOURORGNAME/YOURREPONAME/build/ -H 'Authorization: Bearer <token>'
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)
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
curl -X POST -H "Authorization: Bearer USD{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://USD{quay_registry}/api/v1/repository/USD{orga}/USD{repo}/mirror | jq
curl -X POST -H "Authorization: Bearer USD{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://USD{quay_registry}/api/v1/repository/USD{orga}/USD{repo}/mirror | jq