Chapter 6. Red Hat Quay API examples
Red Hat Quay API examples show how to call common endpoints for applications, discovery, errors, messages, and logs. You can adapt these examples for your registry workflows.
6.1. Managing a user application by using the API
To create, list, or delete a user application token without sharing your password, you can use the Red Hat Quay API. User application tokens work like encrypted username and password credentials for Docker, Podman, or other clients.
Red Hat Quay users can create, list information about, and delete a user application that can be used as an alternative to using your password for Docker, Podman, or other service providers. User application tokens work like your username and password, but are encrypted and do not provide any information to third parties regarding who is accessing Red Hat Quay.
After creation by using the CLI, the user application token is listed under User Settings of the Red Hat Quay UI. Note that this differs from an application token that is created under user settings, and should be considered a different application entirely.
Prerequisites
- You have created an OAuth 2 access token.
Procedure
Create a user application by entering the
POST /api/v1/user/apptokenAPI call:$ curl -X POST \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "title": "MyAppToken" }' \ "http://quay-server.example.com/api/v1/user/apptoken"Example output
{"token": {"uuid": "6b5aa827-cee5-4fbe-a434-4b7b8a245ca7", "title": "MyAppToken", "last_accessed": null, "created": "Wed, 08 Jan 2025 19:32:48 -0000", "expiration": null, "token_code": "string"}}You can obtain information about your application, including when the application expires, by using the
GET /api/v1/user/apptokencommand. For example:$ curl -X GET \ -H "Authorization: Bearer <access_token>" \ "http://quay-server.example.com/api/v1/user/apptoken"Example output
{"tokens": [{"uuid": "6b5aa827-cee5-4fbe-a434-4b7b8a245ca7", "title": "MyAppToken", "last_accessed": null, "created": "Wed, 08 Jan 2025 19:32:48 -0000", "expiration": null}], "only_expiring": null}You can obtain information about a specific user application by entering the
GET /api/v1/user/apptoken/{token_uuid}command:$ curl -X GET \ -H "Authorization: Bearer <access_token>" \ "http://quay-server.example.com/api/v1/user/apptoken/<token_uuid>"Example output
{"token": {"uuid": "6b5aa827-cee5-4fbe-a434-4b7b8a245ca7", "title": "MyAppToken", "last_accessed": null, "created": "Wed, 08 Jan 2025 19:32:48 -0000", "expiration": null, "token_code": "string"}}You can delete or revoke a user application token by using the
DELETE /api/v1/user/apptoken/{token_uuid}endpoint:$ curl -X DELETE \ -H "Authorization: Bearer <access_token>" \ "http://quay-server.example.com/api/v1/user/apptoken/<token_uuid>"This command does not return output in the CLI. You can return a list of tokens by entering one of the aforementioned commands.
6.2. Discovering Red Hat Quay API endpoints
To list available Red Hat Quay API endpoints in Swagger format, you can call the discovery endpoint with an OAuth 2 access token.
Prerequisites
- You have created an OAuth 2 access token.
Procedure
Enter the following
GET /api/v1/discoverycommand to list all of the API endpoints available in the Swagger API format:$ curl -X GET "https://<quay-server.example.com>/api/v1/discovery?query=true" \ -H "Authorization: Bearer <access_token>"Example output
--- : "Manage the tags of a repository."}, {"name": "team", "description": "Create, list and manage an organization's teams."}, {"name": "trigger", "description": "Create, list and manage build triggers."}, {"name": "user", "description": "Manage the current user."}, {"name": "userfiles", "description": ""}]} ---
6.3. Obtaining Red Hat Quay API error details
To retrieve details for a Red Hat Quay API error type, you can call the error endpoint with an OAuth 2 access token and an error code.
Prerequisites
- You have created an OAuth 2 access token.
Procedure
Obtain error details of the API by entering the
GET /api/v1/error/{error_type}endpoint. Note that you must include one of the following error codes:HTTP Code Description 200
Successful invocation
400
Bad Request
401
Session required
403
Unauthorized access
404
Not found
$ curl -X GET "https://<quay-server.example.com>/api/v1/error/<error_type>" \ -H "Authorization: Bearer <access_token>"Example output
curl: (7) Failed to connect to quay-server.example.com port 443 after 0 ms: Couldn't connect to server
6.4. Managing global messages by using the API
To create, list, or delete global messages in Red Hat Quay, you can use the messages API endpoints with an OAuth 2 access token.
Prerequisites
- You have created an OAuth 2 access token.
Procedure
Create a message by using the
POST /api/v1/messageendpoint:$ curl -X POST "https://<quay-server.example.com>/api/v1/messages" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "message": { "content": "Hi", "media_type": "text/plain", "severity": "info" } }'This command does not return output.
Use the
GET /api/v1/messagescommand to return the list of global messages:$ curl -X GET "https://<quay-server.example.com>/api/v1/messages" \ -H "Authorization: Bearer <access_token>"Example output
{"messages": [{"uuid": "ecababd4-3451-4458-b5db-801684137444", "content": "Hi", "severity": "info", "media_type": "text/plain"}]}Delete the global message by using the
DELETE /api/v1/message/{uuid}endpoint:$ curl -X DELETE "https://<quay-server.example.com>/api/v1/message/<uuid>" \ -H "Authorization: Bearer <access_token>"This command does not return output.
6.5. Viewing usage logs by using the API
To review registry activity, you can view usage logs by organization or repository through the Red Hat Quay API. You can aggregate logs, list detailed entries, filter by user or date range, and page through results.
6.5.1. Viewing aggregated logs
To review grouped activity for a user, organization, or repository in Red Hat Quay, you can retrieve aggregated logs through the API. You can filter results by performer and date range.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
GET /api/v1/user/aggregatelogsAPI endpoint to return the aggregated (or grouped) logs for the current user:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "https://<quay-server.example.com>/api/v1/user/aggregatelogs"The following example shows aggregated log output:
{"aggregated": [{"kind": "create_tag", "count": 1, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}, {"kind": "manifest_label_add", "count": 1, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}, {"kind": "push_repo", "count": 2, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}, {"kind": "revert_tag", "count": 1, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}]}You can also pass in the
performerandstarttime/endtimequeries to obtain aggregated logs for a specific user between a specific time period. For example:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "<quay-server.example.com>/api/v1/user/aggregatelogs?performer=<username>&starttime=<MM/DD/YYYY>&endtime=<MM/DD/YYYY>"View aggregated logs by organization by using the
GET /api/v1/organization/{orgname}/aggregatelogsendpoint. For example:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "<quay-server.example.com>/api/v1/organization/{orgname}/aggregatelogs"View aggregated logs by repository by using the
GET /api/v1/repository/{repository}/aggregatelogsendpoint. The following example includes thestarttime/endtimefields:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "<quay-server.example.com>/api/v1/repository/<repository_name>/<namespace>/aggregatelogs?starttime=2024-01-01&endtime=2024-06-18""
6.5.2. Viewing detailed logs
To inspect individual registry events for a user, organization, or repository in Red Hat Quay, you can retrieve detailed logs through the API. You can filter results by performer and date range.
Procedure
Use the
GET /api/v1/user/logsAPI endpoint to return a list of log entries for a user. For example:$ curl -X GET -H "Authorization: Bearer <bearer_token>" -H "Accept: application/json" "<quay-server.example.com>/api/v1/user/logs"You can also pass in the
performerandstarttime/endtimequeries to obtain logs for a specific user between a specific time period. For example:$ curl -X GET -H "Authorization: Bearer <bearer_token>" -H "Accept: application/json" "http://quay-server.example.com/api/v1/user/logs?performer=quayuser&starttime=01/01/2024&endtime=06/18/2024"The following example shows detailed log output:
--- {"start_time": "Mon, 01 Jan 2024 00:00:00 -0000", "end_time": "Wed, 19 Jun 2024 00:00:00 -0000", "logs": [{"kind": "revert_tag", "metadata": {"username": "quayuser", "repo": "busybox", "tag": "test-two", "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d"}, "ip": "192.168.1.131", "datetime": "Tue, 18 Jun 2024 18:59:13 -0000", "performer": {"kind": "user", "name": "quayuser", "is_robot": false, "avatar": {"name": "quayuser", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}}}, {"kind": "push_repo", "metadata": {"repo": "busybox", "namespace": "quayuser", "user-agent": "containers/5.30.1 (github.com/containers/image)", "tag": "test-two", "username": "quayuser", } ---Use the
GET /api/v1/organization/{orgname}/logsendpoint to return logs for a specified organization:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "http://<quay-server.example.com>/api/v1/organization/{orgname}/logs"Use the
GET /api/v1/repository/{repository}/logsendpoint to return logs for a specified repository:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "http://<quay-server.example.com>/api/v1/repository/{repository}/logs"
6.6. Exporting logs by using the API
To export detailed Red Hat Quay logs for a user, organization, or repository, you can call the export logs API endpoints and deliver the results to a callback URL or email address.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
POST /api/v1/user/exportlogsendpoint to export logs for the current user:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "starttime": "<MM/DD/YYYY>", "endtime": "<MM/DD/YYYY>", "callback_email": "your.email@example.com" }' \ "http://<quay-server.example.com>/api/v1/user/exportlogs"Example output
{"export_id": "6a0b9ea9-444c-4a19-9db8-113201c38cd4"}Use the
POST /api/v1/organization/{orgname}/exportlogsendpoint to export logs for an organization:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "starttime": "<MM/DD/YYYY>", "endtime": "<MM/DD/YYYY>", "callback_email": "org.logs@example.com" }' \ "http://<quay-server.example.com>/api/v1/organization/{orgname}/exportlogs"Use the
POST /api/v1/repository/{repository}/exportlogsendpoint to export logs for a repository:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "starttime": "2024-01-01", "endtime": "2024-06-18", "callback_url": "http://your-callback-url.example.com" }' \ "http://<quay-server.example.com>/api/v1/repository/{repository}/exportlogs"
6.7. Adding and managing labels by using the API
To add, list, retrieve, or delete labels on image manifests in Red Hat Quay, you can use the repository manifest labels API endpoints with an OAuth 2 access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
GET /api/v1/repository/{repository}/manifest/{manifestref}command to retrieve the details of a specific manifest in a repository:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>Use the
GET /api/v1/repository/{repository}/manifest/{manifestref}/labelscommand to retrieve a list of labels for a specific manifest:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labelsExample output
{"labels": [{"id": "e9f717d2-c1dd-4626-802d-733a029d17ad", "key": "org.opencontainers.image.url", "value": "https://github.com/docker-library/busybox", "source_type": "manifest", "media_type": "text/plain"}, {"id": "2d34ec64-4051-43ad-ae06-d5f81003576a", "key": "org.opencontainers.image.version", "value": "1.36.1-glibc", "source_type": "manifest", "media_type": "text/plain"}]}Use the
GET /api/v1/repository/{repository}/manifest/{manifestref}/labels/{labelid}command to obtain information about a specific manifest:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels/<label_id>Example output
{"id": "e9f717d2-c1dd-4626-802d-733a029d17ad", "key": "org.opencontainers.image.url", "value": "https://github.com/docker-library/busybox", "source_type": "manifest", "media_type": "text/plain"}Add an additional label to a manifest in a given repository with the
POST /api/v1/repository/{repository}/manifest/{manifestref}/labelscommand. For example:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ --data '{ "key": "<key>", "value": "<value>", "media_type": "<media_type>" }' \ https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labelsExample output
{"label": {"id": "346593fd-18c8-49db-854f-4cb1fb76ff9c", "key": "example-key", "value": "example-value", "source_type": "api", "media_type": "text/plain"}}Delete a label by using the
DELETE /api/v1/repository/{repository}/manifest/{manifestref}/labels/{labelid}command:$ curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels/<labelid>This command does not return output in the CLI. You can list labels again to confirm that the label was removed.
6.8. Using the API to mirror a repository
To mirror an external repository into Red Hat Quay, you can create and manage a repository mirror configuration through the API. You can also sync, cancel, or update the configuration.
Prerequisites
-
You have set
FEATURE_REPO_MIRROR: truein yourconfig.yamlfile.
Procedure
Create a new repository mirror configuration by using the
POST /api/v1/repository/{repository}/mirrorendpoint:$ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "is_enabled": <is_enabled>, "external_reference": "<external_reference>", "external_registry_username": "<external_registry_username>", "external_registry_password": "<external_registry_password>", "sync_start_date": "<sync_start_date>", "sync_interval": <sync_interval>, "robot_username": "<robot_username>", "skopeo_timeout_interval": 600, "root_rule": { "rule": "<rule>", "rule_type": "<rule_type>" } }'Return information about the mirror configuration by using the
GET /api/v1/repository/{repository}/mirrorendpoint:$ curl -X GET "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror" \ -H "Authorization: Bearer <access_token>"Example output
{"is_enabled": true, "mirror_type": "PULL", "external_reference": "https://quay.io/repository/argoproj/argocd", "external_registry_username": null, "external_registry_config": {}, "sync_interval": 86400, "sync_start_date": "2025-01-15T12:00:00Z", "sync_expiration_date": null, "sync_retries_remaining": 3, "sync_status": "NEVER_RUN", "root_rule": {"rule_kind": "tag_glob_csv", "rule_value": ["*.latest*"]}, "robot_username": "quayadmin+mirror_robot"}Sync the repositories by using the
POST /api/v1/repository/{repository}/mirror/sync-nowendpoint. For example:$ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror/sync-now" \ -H "Authorization: Bearer <access_token>"This command does not return output in the CLI.
Cancel the sync with the
POST /api/v1/repository/{repository}/mirror/sync-cancelendpoint. For example:$ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror/sync-cancel" \ -H "Authorization: Bearer <access_token>"This command does not return output in the CLI.
After creating a mirror configuration, make changes with the
PUT /api/v1/repository/{repository}/mirrorcommand. For example, you might choose to disable automatic synchronizations:$ curl -X PUT "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "is_enabled": <false>, "external_reference": "<external_reference>", "external_registry_username": "<external_registry_username>", "external_registry_password": "<external_registry_password>", "sync_start_date": "<sync_start_date>", "sync_interval": <sync_interval>, "robot_username": "<robot_username>", "skopeo_timeout_interval": 600, "root_rule": { "rule": "<rule>", "rule_type": "<rule_type>" } }'Where:
"is_enabled": <false>- Disables automatic synchronization.
6.9. Establishing quota with the Red Hat Quay API
Quota policies in Red Hat Quay set storage limits for organizations and users so that you can control registry capacity. You can create, view, update, and delete quota settings through the API.
6.9.1. Managing organization quota with the Red Hat Quay API
To manage storage quota for an organization in Red Hat Quay, you can use the organization quota API endpoints. You can check, create, change, or delete quota limitations.
When an organization is first created, it does not have an established quota.
Prerequisites
- You have generated an OAuth access token.
Procedure
To set a quota for an organization, use the
POST /api/v1/organization/{orgname}/quotaendpoint:$ curl -X POST "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "limit_bytes": 10737418240, "limits": "10 Gi" }'Example output
"Created"Use the
GET /api/v1/organization/{orgname}/quotacommand to return information about the policy, including the ID number, which is required for other organization quota endpoints. For example:$ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' https://example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/api/v1/organization/testorg/quota | jqExample output
[{"id": 1, "limit_bytes": 10737418240, "limit": "10.0 GiB", "default_config": false, "limits": [], "default_config_exists": false}]After you obtain the ID number, you can use the
GET /api/v1/organization/{orgname}/quota/{quota_id}command to list the quota policy. For example:$ curl -X GET "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota/<quota_id>" \ -H "Authorization: Bearer <access_token>"Example output
{"id": 1, "limit_bytes": 10737418240, "limit": "10.0 GiB", "default_config": false, "limits": [], "default_config_exists": false}Use the
PUT /api/v1/organization/{orgname}/quota/{quota_id}command to modify the existing quota limitation. Note that this requires the policy ID. For example:$ curl -X PUT "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota/<quota_id>" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "limit_bytes": <limit_in_bytes> }'Example output
{"id": 1, "limit_bytes": 21474836480, "limit": "20.0 GiB", "default_config": false, "limits": [], "default_config_exists": false}Delete an organization’s quota with the
DELETE /api/v1/organization/{orgname}/quota/{quota_id}command. For example:$ curl -X DELETE "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota/<quota_id>" \ -H "Authorization: Bearer <access_token>"This command does not return output.
6.9.2. Setting quota limits for an organization by using the Red Hat Quay API
To return a warning or deny image pushes when an organization exceeds its quota in Red Hat Quay, you can create, list, update, and delete organization quota limits through the API.
Procedure
Use the
POST /api/v1/organization/{orgname}/quota/{quota_id}/limitcommand to create a quota policy that rejects images if they exceed the allotted quota. For example:$ curl -X POST "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota/<quota_id>/limit" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "limit_bytes": 21474836480, "type": "Reject", "threshold_percent": 90 }'where:
type-
Specifies one of
RejectorWarning. threshold_percentSpecifies the quota threshold, in percent of quota.
Example output
"Created"
Use the
GET /api/v1/organization/{orgname}/quota/{quota_id}/limitcommand to obtain the ID of the quota limit. For example:$ curl -X GET "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota/<quota_id>/limit" \ -H "Authorization: Bearer <access_token>"Example output
[{"id": 2, "type": "Reject", "limit_percent": 90}]Update the policy with the
PUT /api/v1/organization/{orgname}/quota/{quota_id}/limit/{limit_id}endpoint. For example:$ curl -X PUT "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota/<quota_id>/limit/<limit_id>" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "type": "<type>", "threshold_percent": <threshold_percent> }'Example output
{"id": 3, "limit_bytes": 10737418240, "limit": "10.0 GiB", "default_config": false, "limits": [{"id": 2, "type": "Warning", "limit_percent": 80}], "default_config_exists": false}Delete the quota limit with the
DELETE /api/v1/organization/{orgname}/quota/{quota_id}/limit/{limit_id}endpoint:$ curl -X DELETE "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota/<quota_id>/limit/<limit_id>" \ -H "Authorization: Bearer <access_token>"This command does not return output.
6.9.3. Obtaining quota limits for the user with the Red Hat Quay API
To view storage quota and limit policies for the logged-in user in Red Hat Quay, you can call the user quota API endpoints.
Quota limits for users must be set on the Red Hat Quay UI. The following APIs return the quota limits for the user that is logged in.
Procedure
Use the
GET /api/v1/user/quotacommand to return information about the quota limitations:$ curl -X GET "https://<quay-server.example.com>/api/v1/user/quota" \ -H "Authorization: Bearer <access_token>"Example output
[{"id": 4, "limit_bytes": 2199023255552, "limit": "2.0 TiB", "default_config": false, "limits": [], "default_config_exists": false}]After you have received the quota ID, pass it in with the
GET /api/v1/user/quota/{quota_id}endpoint to return information about the limitation:$ curl -X GET "https://<quay-server.example.com>/api/v1/user/quota/{quota_id}" \ -H "Authorization: Bearer <access_token>"Example output
{"id": 4, "limit_bytes": 2199023255552, "limit": "2.0 TiB", "default_config": false, "limits": [], "default_config_exists": false}View the limitations by using the
GET /api/v1/user/quota/{quota_id}/limitendpoint. For example:$ curl -X GET "https://<quay-server.example.com>/api/v1/user/quota/{quota_id}/limit" \ -H "Authorization: Bearer <access_token>"Example output
[{"id": 3, "type": "Reject", "limit_percent": 100}]Return additional information about the entire policy by using the
GET /api/v1/user/quota/{quota_id}/limit/{limit_id}endpoint:$ curl -X GET "https://<quay-server.example.com>/api/v1/user/quota/{quota_id}/limit/{limit_id}" \ -H "Authorization: Bearer <access_token>"Example output
{"id": 4, "limit_bytes": 2199023255552, "limit": "2.0 TiB", "default_config": false, "limits": [{"id": 3, "type": "Reject", "limit_percent": 100}], "default_config_exists": false}
6.10. Managing organizations by using the API
To create and manage organizations in Red Hat Quay, you can use organization API endpoints. You can view organization details, manage members, configure proxy caches, and delete organizations.
6.10.1. Creating an organization by using the Red Hat Quay API
To create an organization in Red Hat Quay, you can call the organization API endpoint with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Enter the following command to create a new organization by using the
POST /api/v1/organization/endpoint:$ curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" -d '{ "name": "<new_organization_name>" }' "https://<quay-server.example.com>/api/v1/organization/"Example output
"Created"After creation, you can change organization details, such as adding an email address, with the
PUT /api/v1/organization/{orgname}command. For example:$ curl -X PUT "https://<quay-server.example.com>/api/v1/organization/<orgname>" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "email": "<org_email>", "invoice_email": <true/false>, "invoice_email_address": "<billing_email>" }'Example output
{"name": "test", "email": "new-contact@test-org.com", "avatar": {"name": "test", "hash": "a15d479002b20f211568fd4419e76686d2b88a4980a5b4c4bc10420776c5f6fe", "color": "#aec7e8", "kind": "user"}, "is_admin": true, "is_member": true, "teams": {"owners": {"name": "owners", "description": "", "role": "admin", "avatar": {"name": "owners", "hash": "6f0e3a8c0eb46e8834b43b03374ece43a030621d92a7437beb48f871e90f8d90", "color": "#c7c7c7", "kind": "team"}, "can_view": true, "repo_count": 0, "member_count": 1, "is_synced": false}}, "ordered_teams": ["owners"], "invoice_email": true, "invoice_email_address": "billing@test-org.com", "tag_expiration_s": 1209600, "is_free_account": true, "quotas": [{"id": 2, "limit_bytes": 10737418240, "limits": [{"id": 1, "type": "Reject", "limit_percent": 90}]}], "quota_report": {"quota_bytes": 0, "configured_quota": 10737418240, "running_backfill": "complete", "backfill_status": "complete"}}
6.10.2. Deleting an organization by using the Red Hat Quay API
To delete an organization in Red Hat Quay, you can call the organization API endpoint with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Enter the following command to delete an organization by using the
DELETE /api/v1/organization/{orgname}endpoint:$ curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ "https://<quay-server.example.com>/api/v1/organization/<organization_name>"The CLI does not return information when you delete an organization. To confirm deletion, you can check the Red Hat Quay UI, or you can enter the
GET /api/v1/organization/{orgname}command to see if details are returned for the deleted organization:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ "<quay-server.example.com>/api/v1/organization/<organization_name>"Example output
{"detail": "Not Found", "error_message": "Not Found", "error_type": "not_found", "title": "not_found", "type": "http://<quay-server.example.com>/api/v1/error/not_found", "status": 404}
6.10.3. Managing organization contact email with the API
Use the organization contact email setting to configure where automated system alerts are sent for an organization. The contact_email field allows multiple organizations to share the same notification address without requiring separate user accounts for each team.
In the Red Hat Quay web UI, the contact_email field is labeled as Organization creation: "Email (Optional)" and Organization Settings page: "Email".
The organization contact_email field has the following properties:
- Receives namespace-level notifications (such as quota warnings and quota errors), billing and payment alerts (invoices, payment failures), and organization account recovery emails.
- Can be shared across multiple organizations (useful for team distribution lists).
- An optional setting; if left empty, notifications default to organization owners.
When FEATURE_ORG_SHARED_EMAIL: false, Red Hat Quay enforces email uniqueness by default so that the same address cannot be used by more than one user or organization entity. This is a backend restriction and not a UI-only rule. It applies during organization creation only, not when you later update an organization contact email. At creation time, the organization contact email cannot match any existing user account email in the system.
When you set FEATURE_ORG_SHARED_EMAIL: true in your config.yaml file, the same email address can be shared across multiple organizations and with at most one user account.
For POST and PUT requests, the API accepts both email and contact_email fields. When both are provided, contact_email takes precedence. The email field is retained for backward compatibility, but new integrations should use contact_email.
Prerequisites
- You have Created an OAuth access token.
- You have organization administrator permissions.
Procedure
To retrieve the current email configured for an organization, use the following
GET /api/v1/organization/{orgname}endpoint:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ "https://<quay-server.example.com>/api/v1/organization/engineering"Example response
{ "name": "engineering", "email": "team-notifications@example.com", "is_admin": true }When an email address is not configured, the API response returns
"email": "".To set the contact email when creating an organization, pass the
contact_emailfield by using thePOST /api/v1/organization/endpoint:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{"name": "engineering", "contact_email": "team-alerts@example.com"}' \ "https://<quay-server.example.com>/api/v1/organization/"To update the contact email for an existing organization, use the
PUT /api/v1/organization/{orgname}endpoint:$ curl -X PUT \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{"contact_email": "new-team-alerts@example.com"}' \ "https://<quay-server.example.com>/api/v1/organization/engineering"To remove the contact email, set
contact_emailtonullor""(empty string). System notifications default to organization owners:$ curl -X PUT \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{"contact_email": ""}' \ "https://<quay-server.example.com>/api/v1/organization/engineering"Multiple organizations can share the same notification address (for example, a team distribution list):
$ curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \ -d '{"email": "devops-team@example.com"}' \ "https://<quay-server.example.com>/api/v1/organization/engineering"$ curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \ -d '{"email": "devops-team@example.com"}' \ "https://<quay-server.example.com>/api/v1/organization/qa-team"NoteWith the default setting (
FEATURE_ORG_SHARED_EMAIL: false), attempting to set an organization email to an address already registered to a user account returnsEmail has already been used: <email>.To allow the same email address to be shared across multiple organizations and with at most one user account, set
FEATURE_ORG_SHARED_EMAIL: truein yourconfig.yamlfile.
6.10.4. Retrieving organization member information by using the API
To list organization members and collaborators or remove a member in Red Hat Quay, you can call the organization members API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
GET /api/v1/organization/{orgname}/membersendpoint to return a list of organization members:$ curl -X GET "https://<quay-server.example.com>/api/v1/organization/<orgname>/members" \ -H "Authorization: Bearer <access_token>"Example output
{"members": [{"name": "quayadmin", "kind": "user", "avatar": {"name": "quayadmin", "hash": "6d640d802fe23b93779b987c187a4b7a4d8fbcbd4febe7009bdff58d84498fba", "color": "#f7b6d2", "kind": "user"}, "teams": [{"name": "owners", "avatar": {"name": "owners", "hash": "6f0e3a8c0eb46e8834b43b03374ece43a030621d92a7437beb48f871e90f8d90", "color": "#c7c7c7", "kind": "team"}}], "repositories": ["testrepo"]}, {"name": "testuser", "kind": "user", "avatar": {"name": "testuser", "hash": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "color": "#6b6ecf", "kind": "user"}, "teams": [{"name": "owners", "avatar": {"name": "owners", "hash": "6f0e3a8c0eb46e8834b43b03374ece43a030621d92a7437beb48f871e90f8d90", "color": "#c7c7c7", "kind": "team"}}], "repositories": []}]}You can use the
GET /api/v1/organization/{orgname}/collaboratorsendpoint to return a list of organization collaborators:$ curl -X GET "https://<quay-server.example.com>/api/v1/organization/{orgname}/collaborators" \ -H "Authorization: Bearer <access_token>"Example output
{"collaborators": [user-test]}Use the
GET /api/v1/organization/{orgname}/members/{membername}endpoint to obtain more specific information about a user:$ curl -X GET "https://<quay-server.example.com>/api/v1/organization/<orgname>/members/<membername>" \ -H "Authorization: Bearer <access_token>"Example output
{"name": "quayadmin", "kind": "user", "avatar": {"name": "quayadmin", "hash": "6d640d802fe23b93779b987c187a4b7a4d8fbcbd4febe7009bdff58d84498fba", "color": "#f7b6d2", "kind": "user"}, "teams": [{"name": "owners", "avatar": {"name": "owners", "hash": "6f0e3a8c0eb46e8834b43b03374ece43a030621d92a7437beb48f871e90f8d90", "color": "#c7c7c7", "kind": "team"}}], "repositories": ["testrepo"]}Use the
DELETE /api/v1/organization/{orgname}/members/{membername}endpoint to delete a team member.$ curl -X DELETE "https://<quay-server.example.com>/api/v1/organization/<orgname>/members/<membername>" \ -H "Authorization: Bearer <access_token>"This command does not return output.
6.10.5. Managing an organization application by using the Red Hat Quay API
To create, list, update, or delete organization applications in Red Hat Quay, you can call the organization applications API endpoints with an OAuth access token.
After you create an organization application in the UI, create and manage OAuth 2 access tokens from the application’s API Access Tokens page.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
POST /api/v1/organization/{orgname}/applicationsendpoint to create a new application for your organization. For example:$ curl -X POST "https://<quay-server.example.com>/api/v1/organization/<orgname>/applications" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "name": "<app_name>", "redirect_uri": "<redirect_uri>", "application_uri": "<application_uri>", "description": "<app_description>", "avatar_email": "<avatar_email>" }'Example output
{"name": "new-application", "description": "", "application_uri": "", "client_id": "E6GJSHOZMFBVNHTHNB53", "client_secret": "SANSWCWSGLVAUQ60L4Q4CEO3C1QAYGEXZK2VKJNI", "redirect_uri": "", "avatar_email": null}Use the
GET /api/v1/organization/{orgname}/applicationsendpoint to return a list of all organization applications. For example:$ curl -X GET "https://<quay-server.example.com>/api/v1/organization/<orgname>/applications" \ -H "Authorization: Bearer <access_token>"Example output
{"applications": [{"name": "test", "description": "", "application_uri": "", "client_id": "MCJ61D8KQBFS2DXM56S2", "client_secret": "J5G7CCX5QCA8Q5XZLWGI7USJPSM4M5MQHJED46CF", "redirect_uri": "", "avatar_email": null}, {"name": "new-token", "description": "", "application_uri": "", "client_id": "IG58PX2REEY9O08IZFZE", "client_secret": "2LWTWO89KH26P2CO4TWFM7PGCX4V4SUZES2CIZMR", "redirect_uri": "", "avatar_email": null}, {"name": "second-token", "description": "", "application_uri": "", "client_id": "6XBK7QY7ACSCN5XBM3GS", "client_secret": "AVKBOUXTFO3MXBBK5UJD5QCQRN2FWL3O0XPZZT78", "redirect_uri": "", "avatar_email": null}, {"name": "new-application", "description": "", "application_uri": "", "client_id": "E6GJSHOZMFBVNHTHNB53", "client_secret": "SANSWCWSGLVAUQ60L4Q4CEO3C1QAYGEXZK2VKJNI", "redirect_uri": "", "avatar_email": null}]}You can also return applications for a specific client by using the
GET /api/v1/organization/{orgname}/applications/{client_id}endpoint. For example:$ curl -X GET "https://<quay-server.example.com>/api/v1/organization/<orgname>/applications/<client_id>" \ -H "Authorization: Bearer <access_token>"Example output
{"name": "test", "description": "", "application_uri": "", "client_id": "MCJ61D8KQBFS2DXM56S2", "client_secret": "J5G7CCX5QCA8Q5XZLWGI7USJPSM4M5MQHJED46CF", "redirect_uri": "", "avatar_email": null}After creation, you can update organization applications, for example to add a redirect URI or a new description, by using the
PUT /api/v1/organization/{orgname}/applications/{client_id}endpoint:$ curl -X PUT "https://quay-server.example.com/api/v1/organization/test/applications/12345" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Application Name", "redirect_uri": "https://example.com/oauth/callback", "application_uri": "https://example.com", "description": "Updated description for the application", "avatar_email": "avatar@example.com" }'After creation, you can return application information by using the
GET /api/v1/app/{client_id}endpoint:$ curl -X GET "https://<quay-server.example.com>/api/v1/app/<client_id>" \ -H "Authorization: Bearer <access_token>"Example output
{"name": "new-application3", "description": "", "uri": "", "avatar": {"name": "new-application3", "hash": "a15d479002b20f211568fd4419e76686d2b88a4980a5b4c4bc10420776c5f6fe", "color": "#aec7e8", "kind": "app"}, "organization": {"name": "test", "email": "new-contact@test-org.com", "avatar": {"name": "test", "hash": "a15d479002b20f211568fd4419e76686d2b88a4980a5b4c4bc10420776c5f6fe", "color": "#aec7e8", "kind": "user"}, "is_admin": true, "is_member": true, "teams": {}, "ordered_teams": [], "invoice_email": true, "invoice_email_address": "billing@test-org.com", "tag_expiration_s": 1209600, "is_free_account": true, "quotas": [{"id": 2, "limit_bytes": 10737418240, "limits": [{"id": 1, "type": "Reject", "limit_percent": 90}]}], "quota_report": {"quota_bytes": 0, "configured_quota": 10737418240, "running_backfill": "complete", "backfill_status": "complete"}}}You can delete organization applications with the
DELETE /api/v1/organization/{orgname}/applications/{client_id}endpoint. For example:$ curl -X DELETE "https://<quay-server.example.com>/api/v1/organization/{orgname}/applications/{client_id}" \ -H "Authorization: Bearer <access_token>"This command does not return output.
6.10.6. Configuring a proxy cache for an organization by using the Red Hat Quay API
To create, validate, view, or delete a proxy cache configuration for an organization in Red Hat Quay, you can call the organization proxycache API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
POST /api/v1/organization/{orgname}/proxycacheendpoint to create a proxy cache configuration for the organization.$ curl -X POST "https://<quay-server.example.com>/api/v1/organization/<orgname>/proxycache" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "upstream_registry": "<upstream_registry>" "upstream_registry_username": "your_robot_account_username" "upstream_registry_password": "your_robot_account_password" }'Use the
POST /api/v1/organization/{orgname}/validateproxycacheendpoint to validate the proxy configuration:$ curl -X POST "https://<quay-server.example.com>/api/v1/organization/{orgname}/validateproxycache" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "upstream_registry": "<upstream_registry>" "upstream_registry_username": "your_robot_account_username" "upstream_registry_password": "your_robot_account_password" }'Use the
GET /api/v1/organization/{orgname}/proxycacheendpoint to obtain information about the proxy cache. For example:$ curl -X GET "https://<quay-server.example.com>/api/v1/organization/{orgname}/proxycache" \ -H "Authorization: Bearer <access_token>"Example output
{"upstream_registry": "quay.io", "expiration_s": 86400, "insecure": false}Use the
DELETE /api/v1/organization/{orgname}/proxycacheendpoint to delete the proxy cache configuration:$ curl -X DELETE "https://<quay-server.example.com>/api/v1/organization/{orgname}/proxycache" \ -H "Authorization: Bearer <access_token>"Example output
"Deleted"
6.11. Managing repository permissions by using the Red Hat Quay API
To create, view, and delete user and team access on a repository in Red Hat Quay, you can manage repository permissions through the API.
6.11.1. Managing user permissions by using the Red Hat Quay API
To view, change, or remove a user role on a repository in Red Hat Quay, you can call the repository user permissions API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
GET /api/v1/repository/{repository}/permissions/user/{username}endpoint to obtain repository permissions for a user. For example:$ curl -X GET \ -H "Authorization: Bearer <access_token>" \ "https://quay-server.example.com/api/v1/repository/<repository_path>/permissions/user/<username>"Example output
{"role": "read", "name": "testuser", "is_robot": false, "avatar": {"name": "testuser", "hash": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "color": "#6b6ecf", "kind": "user"}, "is_org_member": false}Return all user permissions with the
GET /api/v1/repository/{repository}/permissions/user/endpoint:$ curl -X GET \ -H "Authorization: Bearer <access_token>" \ "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/user/"Example output
{"permissions": {"quayadmin": {"role": "admin", "name": "quayadmin", "is_robot": false, "avatar": {"name": "quayadmin", "hash": "6d640d802fe23b93779b987c187a4b7a4d8fbcbd4febe7009bdff58d84498fba", "color": "#f7b6d2", "kind": "user"}, "is_org_member": true}, "test+example": {"role": "admin", "name": "test+example", "is_robot": true, "avatar": {"name": "test+example", "hash": "3b03050c26e900500437beee4f7f2a5855ca7e7c5eab4623a023ee613565a60e", "color": "#a1d99b", "kind": "robot"}, "is_org_member": true}}}Alternatively, use the
GET /api/v1/repository/{repository}/permissions/user/{username}/transitiveendpoint to return only the repository permission for the user:$ curl -X GET \ -H "Authorization: Bearer <access_token>" \ "https://quay-server.example.com/api/v1/repository/<repository_path>/permissions/user/<username>/transitive"Example output
{"permissions": [{"role": "admin"}]}Change the user’s permissions, such as making the user an
admin, by using thePUT /api/v1/repository/{repository}/permissions/user/{username}endpoint. For example:$ curl -X PUT \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{"role": "<role>"}' \ "https://quay-server.example.com/api/v1/repository/<repository_path>/permissions/user/<username>"Example output
{"role": "admin", "name": "testuser", "is_robot": false, "avatar": {"name": "testuser", "hash": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "color": "#6b6ecf", "kind": "user"}, "is_org_member": false}Delete user permissions by using the
DELETE /api/v1/repository/{repository}/permissions/user/{username}endpoint. For example:$ curl -X DELETE \ -H "Authorization: Bearer <access_token>" \ "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/user/<username>"This command does not return output.
6.11.2. Managing team permissions by using the Red Hat Quay API
To view, change, or remove a team role on a repository in Red Hat Quay, you can call the repository team permissions API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Return permissions for a specified team by using the
GET /api/v1/repository/{repository}/permissions/team/{teamname}endpoint:$ curl -X GET \ -H "Authorization: Bearer <access_token>" \ "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/team/<teamname>"Example output
{"role": "write"}Return permissions for all teams with the
GET /api/v1/repository/{repository}/permissions/team/endpoint. For example:$ curl -X GET \ -H "Authorization: Bearer <access_token>" \ "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/team/"Example output
{"permissions": {"ironmanteam": {"role": "read", "name": "ironmanteam", "avatar": {"name": "ironmanteam", "hash": "8045b2361613622183e87f33a7bfc54e100a41bca41094abb64320df29ef458d", "color": "#969696", "kind": "team"}}, "sillyteam": {"role": "read", "name": "sillyteam", "avatar": {"name": "sillyteam", "hash": "f275d39bdee2766d2404e2c6dbff28fe290969242e9fcf1ffb2cde36b83448ff", "color": "#17becf", "kind": "team"}}}}Change permissions for a specified team by using the
PUT /api/v1/repository/{repository}/permissions/team/{teamname}command. For example:$ curl -X PUT \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{"role": "<role>"}' \ "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/team/<teamname>"Example output
{"role": "admin", "name": "superteam", "avatar": {"name": "superteam", "hash": "48cb6d114200039fed5c601480653ae7371d5a8849521d4c3bf2418ea013fc0f", "color": "#9467bd", "kind": "team"}}Delete team permissions with the
DELETE /api/v1/repository/{repository}/permissions/team/{teamname}command. For example:$ curl -X DELETE \ -H "Authorization: Bearer <access_token>" \ "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/team/<teamname>"This command does not return output in the CLI.
6.12. Managing auto-prune policies by using the Red Hat Quay API
To create, retrieve, update, and delete auto-prune policies for organizations, repositories, and users in Red Hat Quay, you can use the auto-prune policy API endpoints.
6.12.1. Creating an auto-prune policy for a namespace by using the Red Hat Quay API
To create, update, view, or delete an organization auto-prune policy in Red Hat Quay, you can use the organization autoprunepolicy API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
- You have logged into Red Hat Quay.
Procedure
Enter the following
POST /api/v1/organization/{orgname}/autoprunepolicy/command to create a new policy that limits the number of tags allowed in an organization:$ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags", "value": 10}' http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/Alternatively, you can set tags to expire for a specified time after their creation date:
$ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{ "method": "creation_date", "value": "7d"}' http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/Example output
{"uuid": "73d64f05-d587-42d9-af6d-e726a4a80d6e"}Optional. You can add an additional policy to an organization and pass in the
tagPatternandtagPatternMatchesfields to prune only tags that match the given regex pattern. For example:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{ "method": "creation_date", "value": "7d", "tagPattern": "^v*", "tagPatternMatches": true }' \ "https://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/"where:
tagPatternMatches-
Specifies that the
truevalue prunes tags that match the given regex pattern. In this example, tags that match^v*are pruned.
You can update your organization’s auto-prune policy by using the
PUT /api/v1/organization/{orgname}/autoprunepolicy/{policy_uuid}command. For example:$ curl -X PUT -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" -d '{ "method": "creation_date", "value": "4d", "tagPattern": "^v*", "tagPatternMatches": true }' "<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/<uuid>"This command does not return output. Continue to the next step.
Check your auto-prune policy by entering the following command:
$ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/Example output
{"policies": [{"uuid": "ebf7448b-93c3-4f14-bf2f-25aa6857c7b0", "method": "creation_date", "value": "4d", "tagPattern": "^v*", "tagPatternMatches": true}, {"uuid": "da4d0ad7-3c2d-4be8-af63-9c51f9a501bc", "method": "number_of_tags", "value": 10, "tagPattern": null, "tagPatternMatches": true}, {"uuid": "17b9fd96-1537-4462-a830-7f53b43f94c2", "method": "creation_date", "value": "7d", "tagPattern": "^v*", "tagPatternMatches": true}]}You can delete the auto-prune policy for your organization by entering the following command. Note that deleting the policy requires the UUID.
$ curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/73d64f05-d587-42d9-af6d-e726a4a80d6e
6.12.2. Creating an auto-prune policy for a namespace for the current user by using the API
To manage auto-prune policies for your own user namespace in Red Hat Quay, you can use the /api/v1/user/autoprunepolicy/ API endpoints.
The use of /user/ in the following commands represents the user that is currently logged into Red Hat Quay.
Prerequisites
- You have created an OAuth access token.
- You have logged into Red Hat Quay.
Procedure
Enter the following
POSTcommand to create a new policy that limits the number of tags for the current user:$ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags", "value": 10}' http://<quay-server.example.com>/api/v1/user/autoprunepolicy/Example output
{"uuid": "8c03f995-ca6f-4928-b98d-d75ed8c14859"}Check your auto-prune policy by entering the following command:
$ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/user/autoprunepolicy/Alternatively, you can include the UUID:
$ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/user/autoprunepolicy/8c03f995-ca6f-4928-b98d-d75ed8c14859Example output
{"policies": [{"uuid": "8c03f995-ca6f-4928-b98d-d75ed8c14859", "method": "number_of_tags", "value": 10}]}You can delete the auto-prune policy by entering the following command. Note that deleting the policy requires the UUID.
$ curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/user/autoprunepolicy/8c03f995-ca6f-4928-b98d-d75ed8c14859Example output
{"uuid": "8c03f995-ca6f-4928-b98d-d75ed8c14859"}
6.12.3. Creating an auto-prune policy for a repository using the Red Hat Quay API
To create, update, view, or delete a repository auto-prune policy in Red Hat Quay, you can use the repository autoprunepolicy API endpoints.
Prerequisites
- You have created an OAuth access token.
- You have logged into Red Hat Quay.
Procedure
Enter the following
POST /api/v1/repository/<repository>/autoprunepolicy/command to create a new policy that limits the number of tags allowed in a repository:$ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags","value": 2}' http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/Alternatively, you can set tags to expire for a specified time after their creation date:
$ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "creation_date", "value": "7d"}' http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/Example output
{"uuid": "ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7"}Optional. You can add an additional policy and pass in the
tagPatternandtagPatternMatchesfields to prune only tags that match the given regex pattern. For example:$ curl -X POST \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "method": "creation_date", "value": "7d", "tagPattern": "^test.", "tagPatternMatches": false }' \ "https://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/"Where:
tagPatternMatches-
Specifies that the
falsevalue prunes tags that do not match the given regex pattern. In this example, all tags except those that match^test.are pruned.
You can update your policy for the repository by using the
PUT /api/v1/repository/<repository>/autoprunepolicy/<policy_uuid>command and passing in the UUID. For example:$ curl -X PUT \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{ "method": "number_of_tags", "value": "5", "tagPattern": "^test.*", "tagPatternMatches": true }' \ "https://quay-server.example.com/api/v1/repository/<namespace>/<repo_name>/autoprunepolicy/<uuid>"This command does not return output. Continue to the next step to check your auto-prune policy.
Check your auto-prune policy by entering the following command:
$ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/Alternatively, you can include the UUID:
$ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7Example output
{"policies": [{"uuid": "ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7", "method": "number_of_tags", "value": 10}]}You can delete the auto-prune policy by entering the following command. Note that deleting the policy requires the UUID.
$ curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7Example output
{"uuid": "ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7"}
6.12.4. Creating an auto-prune policy on a repository for a user with the API
To manage auto-prune policies on another user repository in Red Hat Quay, you can use the repository autoprunepolicy API endpoints when you have admin privileges.
Prerequisites
- You have created an OAuth access token.
- You have logged into Red Hat Quay.
-
You have
adminprivileges on the repository that you are creating the policy for.
Procedure
Enter the following
POST /api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/command to create a new policy that limits the number of tags for the user:$ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags","value": 2}' https://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/Example output
{"uuid": "7726f79c-cbc7-490e-98dd-becdc6fefce7"}Optional. You can add an additional policy for the current user and pass in the
tagPatternandtagPatternMatchesfields to prune only tags that match the given regex pattern. For example:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{ "method": "creation_date", "value": "7d", "tagPattern": "^v*", "tagPatternMatches": true }' \ "http://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/"Example output
{"uuid": "b3797bcd-de72-4b71-9b1e-726dabc971be"}You can update your policy for the current user by using the
PUT /api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/<policy_uuid>command. For example:$ curl -X PUT -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" -d '{ "method": "creation_date", "value": "4d", "tagPattern": "^test.", "tagPatternMatches": true }' "https://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/<policy_uuid>"Updating a policy does not return output in the CLI.
Check your auto-prune policy by entering the following command:
$ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/Alternatively, you can include the UUID:
$ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/7726f79c-cbc7-490e-98dd-becdc6fefce7Example output
{"uuid": "81ee77ec-496a-4a0a-9241-eca49437d15b", "method": "creation_date", "value": "7d", "tagPattern": "^v*", "tagPatternMatches": true}You can delete the auto-prune policy by entering the following command. Note that deleting the policy requires the UUID.
$ curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/<policy_uuid>Example output
{"uuid": "7726f79c-cbc7-490e-98dd-becdc6fefce7"}
6.13. Creating and configuring repositories by using the Red Hat Quay API
To create, retrieve, update, and delete repositories in Red Hat Quay, you can use the repository API endpoints.
6.13.1. Creating and configuring repositories by using the Red Hat Quay API
To create a repository and manage its visibility, details, and description in Red Hat Quay, you can call the repository API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Enter the following command to create a repository by using the
POST /api/v1/repositoryendpoint:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{ "repository": "<new_repository_name>", "visibility": "<private>", "description": "<This is a description of the new repository>." }' \ "https://quay-server.example.com/api/v1/repository"Example output
{"namespace": "quayadmin", "name": "<new_repository_name>", "kind": "image"}You can list repositories with the
GET /api/v1/repositoryendpoint. For example:$ curl -X GET \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ "https://quay-server.example.com/api/v1/repository?public=true&starred=false&namespace=<NAMESPACE>"Example output
{"repositories": [{"namespace": "quayadmin", "name": "busybox", "description": null, "is_public": false, "kind": "image", "state": "MIRROR", "is_starred": false, "quota_report": {"quota_bytes": 2280675, "configured_quota": 2199023255552}}]}Change visibility from public to private with the
POST /api/v1/repository/{repository}/changevisibilityendpoint:$ curl -X POST \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "visibility": "private" }' \ "https://quay-server.example.com/api/v1/repository/<NAMESPACE>/<REPO_NAME>/changevisibility"Example output
{"success": true}You can check the Red Hat Quay UI, or you can enter the following
GET /api/v1/repository/{repository}command to return details about a repository:$ curl -X GET -H "Authorization: Bearer <bearer_token>" "<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>"Example output
{"detail": "Not Found", "error_message": "Not Found", "error_type": "not_found", "title": "not_found", "type": "http://quay-server.example.com/api/v1/error/not_found", "status": 404}Update repository descriptions with the
PUT /api/v1/repository/{repository}endpoint:$ curl -X PUT \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{ "description": "This is an updated description for the repository." }' \ "https://quay-server.example.com/api/v1/repository/<NAMESPACE>/<REPOSITORY>"Example output
{"success": true}Enter the following command to delete a repository by using the
DELETE /api/v1/repository/{repository}endpoint:$ curl -X DELETE -H "Authorization: Bearer <bearer_token>" "<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>"This command does not return output in the CLI.
6.13.2. Creating notifications by using the API
To create, test, reset, or delete repository notifications in Red Hat Quay, you can use the repository notification API endpoints.
Prerequisites
- You have created a repository.
- You have administrative privileges for the repository.
- You have created an OAuth access token.
Procedure
Enter the following
POST /api/v1/repository/{repository}/notificationcommand to create a notification on your repository:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ --data '{ "event": "<event>", "method": "<method>", "config": { "<config_key>": "<config_value>" }, "eventConfig": { "<eventConfig_key>": "<eventConfig_value>" } }' \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/This command does not return output in the CLI. Instead, you can enter the following
GET /api/v1/repository/{repository}/notification/{uuid}command to obtain information about the repository notification:{"uuid": "240662ea-597b-499d-98bb-2b57e73408d6", "title": null, "event": "repo_push", "method": "quay_notification", "config": {"target": {"name": "quayadmin", "kind": "user", "is_robot": false, "avatar": {"name": "quayadmin", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}}}, "event_config": {}, "number_of_failures": 0}You can test your repository notification by entering the following
POST /api/v1/repository/{repository}/notification/{uuid}/testcommand:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>/testExample output
{}You can reset repository notification failures to 0 by entering the following
POST /api/v1/repository/{repository}/notification/{uuid}command:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>Enter the following
DELETE /api/v1/repository/{repository}/notification/{uuid}command to delete a repository notification:$ curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/<uuid>This command does not return output in the CLI. Instead, you can enter the following
GET /api/v1/repository/{repository}/notification/command to retrieve a list of all notifications:$ curl -X GET -H "Authorization: Bearer <bearer_token>" -H "Accept: application/json" https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notificationExample output
{"notifications": []}
6.14. Creating and configuring robot accounts by using the Red Hat Quay API
To create, retrieve, update, and delete robot accounts for organizations and users in Red Hat Quay, you can use the robot account API endpoints.
6.14.1. Creating a robot account by using the Red Hat Quay API
To automate access to your repositories, you can create a robot account by using the Red Hat Quay API. You can create robot accounts for an organization or for your own user account.
Prerequisites
- You have created an OAuth access token.
Procedure
Enter the following command to create a new robot account for an organization by using the
PUT /api/v1/organization/{orgname}/robots/{robot_shortname}endpoint:$ curl -X PUT -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/organization/<organization_name>/robots/<robot_name>"Example output
{"name": "orgname+robot-name", "created": "Fri, 10 May 2024 15:11:00 -0000", "last_accessed": null, "description": "", "token": "<example_secret>", "unstructured_metadata": null}Enter the following command to create a new robot account for the current user with the
PUT /api/v1/user/robots/{robot_shortname}endpoint:$ curl -X PUT -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/user/robots/<robot_name>"Example output
{"name": "quayadmin+robot-name", "created": "Fri, 10 May 2024 15:24:57 -0000", "last_accessed": null, "description": "", "token": "<example_secret>", "unstructured_metadata": null}
6.14.2. Obtaining robot account information by using the Red Hat Quay API
To review robot account details and permissions for an organization or user in Red Hat Quay, you can call the robot account API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
GET /api/v1/organization/{orgname}/robots/{robot_shortname}API endpoint to return information for a robot for an organization:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ "https://quay-server.example.com/api/v1/organization/<ORGNAME>/robots/<ROBOT_SHORTNAME>"Example output
{"name": "test+example", "created": "Mon, 25 Nov 2024 16:25:16 -0000", "last_accessed": null, "description": "", "token": "string", "unstructured_metadata": {}}Use the
GET /api/v1/organization/{orgname}/robots/{robot_shortname}/permissionsendpoint to return the list of permissions for a specific organization robot:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ "https://quay-server.example.com/api/v1/organization/<ORGNAME>/robots/<ROBOT_SHORTNAME>/permissions"Example output
{"permissions": [{"repository": {"name": "testrepo", "is_public": true}, "role": "admin"}]}Use the
GET /api/v1/user/robots/{robot_shortname}API endpoint to return the user’s robot with the specified name:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ "https://quay-server.example.com/api/v1/user/robots/<ROBOT_SHORTNAME>"Example output
{"name": "quayadmin+mirror_robot", "created": "Wed, 15 Jan 2025 17:22:09 -0000", "last_accessed": null, "description": "", "token": "<token_example>", "unstructured_metadata": {}}Use the
GET /api/v1/user/robots/{robot_shortname}/permissionsAPI endpoint to return a list of permissions for the user robot:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ "https://quay-server.example.com/api/v1/user/robots/<ROBOT_SHORTNAME>/permissions"Example output
{"permissions": [{"repository": {"name": "busybox", "is_public": false}, "role": "write"}]}
6.14.3. Deleting a robot account by using the Red Hat Quay API
To remove a robot account that you no longer need, you can delete it by using the Red Hat Quay API. You can delete robot accounts that belong to an organization or to your own user account.
Prerequisites
- You have created an OAuth access token.
Procedure
Enter the following command to delete a robot account for an organization by using the
DELETE /api/v1/organization/{orgname}/robots/{robot_shortname}endpoint:$ curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ "<quay-server.example.com>/api/v1/organization/<organization_name>/robots/<robot_shortname>"The CLI does not return information when deleting a robot account with the API. To confirm deletion, you can check the Red Hat Quay UI, or you can enter the following
GET /api/v1/organization/{orgname}/robotscommand to see if details are returned for the robot account:$ curl -X GET -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/organization/<organization_name>/robots"Example output
{"robots": []}Enter the following command to delete a robot account for the current user with the
DELETE /api/v1/user/robots/{robot_shortname}endpoint:$ curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ "<quay-server.example.com>/api/v1/user/robots/<robot_shortname>"The CLI does not return information when deleting a robot account for the current user with the API. To confirm deletion, you can check the Red Hat Quay UI, or you can enter the following
GET /api/v1/user/robots/{robot_shortname}command to see if details are returned for the robot account:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ "<quay-server.example.com>/api/v1/user/robots/<robot_shortname>"Example output
{"message":"Could not find robot with specified username"}
6.15. Searching against registry context
To find repositories, entities, and other registry resources in Red Hat Quay, you can use the search API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
GET /api/v1/find/repositoriesendpoint to get a list of apps and repositories that match the specified query:$ curl -X GET "https://quay-server.example.com/api/v1/find/repositories?query=<repo_name>&page=1&includeUsage=true" \ -H "Authorization: Bearer <bearer_token>"Example output
{"results": [], "has_additional": false, "page": 2, "page_size": 10, "start_index": 10}Use the
GET /api/v1/find/allendpoint to get a list of entities and resources that match the specified query:$ curl -X GET "https://quay-server.example.com/api/v1/find/all?query=<mysearchterm>" \ -H "Authorization: Bearer <bearer_token>"Example output
{"results": [{"kind": "repository", "title": "repo", "namespace": {"title": "user", "kind": "user", "avatar": {"name": "quayadmin", "hash": "6d640d802fe23b93779b987c187a4b7a4d8fbcbd4febe7009bdff58d84498fba", "color": "#f7b6d2", "kind": "user"}, "name": "quayadmin", "score": 1, "href": "/user/quayadmin"}, "name": "busybox", "description": null, "is_public": false, "score": 4.0, "href": "/repository/quayadmin/busybox"}]}Use the
GET /api/v1/entities/{prefix}endpoint to get a list of entities that match the specified prefix.$ curl -X GET "https://quay-server.example.com/api/v1/entities/<prefix>?includeOrgs=<true_or_false>&includeTeams=<true_or_false>&namespace=<namespace>" \ -H "Authorization: Bearer <bearer_token>"Example output
{"results": [{"name": "quayadmin", "kind": "user", "is_robot": false, "avatar": {"name": "quayadmin", "hash": "6d640d802fe23b93779b987c187a4b7a4d8fbcbd4febe7009bdff58d84498fba", "color": "#f7b6d2", "kind": "user"}}]}
6.16. Viewing Clair security scans by using the API
To view Clair security scan results for a repository manifest in Red Hat Quay, you can call the manifest security API endpoint with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
GET /api/v1/repository/{repository}/manifest/{manifestref}/securityendpoint to retrieve security information about a specific manifest in a repository. For example:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/manifest/<manifest_digest>/security?vulnerabilities=<true_or_false>"Example output
{"status": "queued", "data": null}
6.17. Managing your deployment as a superuser with the Red Hat Quay API
To create, list, change, and delete users, service keys, quotas, and other registry resources as a superuser in Red Hat Quay, you can use the Red Hat Quay API.
6.17.1. Creating a user account by using the Red Hat Quay API
To create a user account in Red Hat Quay as a superuser, you can use the Red Hat Quay API.
Prerequisites
- You are logged into your Red Hat Quay deployment as a superuser.
- You have created an OAuth access token.
Procedure
Enter the following command to create a new user by using the
POST /api/v1/superuser/users/endpoint:$ curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" -d '{ "username": "newuser", "email": "newuser@example.com" }' "https://<quay-server.example.com>/api/v1/superuser/users/"Example output
{"username": "newuser", "email": "newuser@example.com", "password": "123456789", "encrypted_password": "<example_encrypted_password>/JKY9pnDcsw="}Navigate to your Red Hat Quay registry endpoint, for example,
quay-server.example.comand log in with the username and password generated from the API call. In this scenario, the username isnewuserand the password is123456789. Alternatively, you can log in to the registry with the CLI. For example:$ podman login <quay-server.example.com>Example output
username: newuser password: 123456789Optional. You can obtain a list of all users, including superusers, by using the
GET /api/v1/superuser/users/endpoint:$ curl -X GET -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/superuser/users/"NoteThe
GET /api/v1/superuser/users/endpoint only returns users and superusers ifAUTHENTICATION_TYPE: Databaseis set in yourconfig.yamlfile. It does not work forLDAPauthentication types.Example output
{"users": [{"kind": "user", "name": "quayadmin", "username": "quayadmin", "email": "quay@quay.com", "verified": true, "avatar": {"name": "quayadmin", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}, "super_user": true, "enabled": true}, {"kind": "user", "name": "newuser", "username": "newuser", "email": "newuser@example.com", "verified": true, "avatar": {"name": "newuser", "hash": "f338a2c83bfdde84abe2d3348994d70c34185a234cfbf32f9e323e3578e7e771", "color": "#9edae5", "kind": "user"}, "super_user": false, "enabled": true}]}
6.17.2. Deleting a user by using the Red Hat Quay API
To delete a user account from Red Hat Quay as a superuser, you can use the Red Hat Quay API.
After deleting the user, any repositories that this user had in their private account become unavailable.
Prerequisites
- You are logged into your Red Hat Quay deployment as a superuser.
- You have created an OAuth access token.
Procedure
Enter the following
DELETE /api/v1/superuser/users/{username}command to delete a user from the command line:$ curl -X DELETE -H "Authorization: Bearer <insert token here>" https://<quay-server.example.com>/api/v1/superuser/users/<username>The CLI does not return information when deleting a user from the CLI. To confirm deletion, you can check the Red Hat Quay UI by navigating to Superuser Admin Panel
Users, or by entering the following GET /api/v1/superuser/users/command. You can then check to see if they are present.NoteThe
GET /api/v1/superuser/users/endpoint only returns users and superusers ifAUTHENTICATION_TYPE: Databaseis set in yourconfig.yamlfile. It does not work forLDAPauthentication types.$ curl -X GET -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/superuser/users/"
6.17.3. Managing organizations as a superuser with the Red Hat Quay API
To list, update, or delete organizations in Red Hat Quay, you can use the superuser organization API endpoints.
Prerequisites
- You have created an OAuth access token.
- You are logged into your Red Hat Quay deployment as a superuser.
Procedure
Use the
GET /api/v1/superuser/organizationsendpoint to list all organizations:$ curl -L -X GET \ -H "Authorization: Bearer <bearer_token>" \ "https://<quay_server>/api/v1/superuser/organizations?name=<organization_name>"Example output
{"organizations": [{"name": "fed_test", "email": "fe11fc59-bd09-459a-a21c-b57692d151c9", "avatar": {"name": "fed_test", "hash": "e2ce1fb42ec2e0602362beb64b5ebd1e6ad291b710a0355f9296c16157bef3cb", "color": "#ff7f0e", "kind": "org"}, "quotas": [{"id": 3, "limit_bytes": 10737418240, "limits": []}], "quota_report": {"quota_bytes": 0, "configured_quota": 10737418240, "running_backfill": "complete", "backfill_status": "complete"}}, {"name": "test", "email": "new-contact@test-org.com", "avatar": {"name": "test", "hash": "a15d479002b20f211568fd4419e76686d2b88a4980a5b4c4bc10420776c5f6fe", "color": "#aec7e8", "kind": "org"}, "quotas": [{"id": 2, "limit_bytes": 10737418240, "limits": [{"id": 1, "type": "Reject", "limit_percent": 90}]}], "quota_report": {"quota_bytes": 0, "configured_quota": 10737418240, "running_backfill": "complete", "backfill_status": "complete"}}]}Use the
PUT /api/v1/superuser/organizations/{name}endpoint to change or update information for an organization:$ curl -X PUT \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{ "email": "<contact_email>", "invoice_email": <boolean_value>, "invoice_email_address": "<invoice_email_address>", "tag_expiration_s": <expiration_seconds> }' \ "https://<quay_server>/api/v1/superuser/organizations/<organization_name>"Example output
{"name": "test", "email": "new-contact@test-org.com", "avatar": {"name": "test", "hash": "a15d479002b20f211568fd4419e76686d2b88a4980a5b4c4bc10420776c5f6fe", "color": "#aec7e8", "kind": "org"}, "quotas": [{"id": 2, "limit_bytes": 10737418240, "limits": [{"id": 1, "type": "Reject", "limit_percent": 90}]}], "quota_report": {"quota_bytes": 0, "configured_quota": 10737418240, "running_backfill": "complete", "backfill_status": "complete"}}Use the
DELETE /api/v1/superuser/organizations/{name}endpoint to delete an organization:$ curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ "https://<quay_server>/api/v1/superuser/organizations/<organization_name>"This command does not return output in the CLI.
6.17.4. Listing logs as a superuser with the Red Hat Quay API
To list usage logs or obtain registry size information in Red Hat Quay, you can use the superuser logs and registry size API endpoints.
Prerequisites
- You have created an OAuth access token.
- You are logged into your Red Hat Quay deployment as a superuser.
Procedure
Use the
GET /api/v1/superuser/logsendpoint to list the usage logs for the current system:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ "https://<quay_server>/api/v1/superuser/logs?starttime=<start_time>&endtime=<end_time>&page=<page_number>&next_page=<next_page_token>"Example output
{"start_time": "Mon, 17 Feb 2025 19:29:14 -0000", "end_time": "Wed, 19 Feb 2025 19:29:14 -0000", "logs": [{"kind": "login_success", "metadata": {"type": "quayauth", "useragent": "Mozilla/5.0 (X11; Linux x86_64; rv:134.0) Gecko/20100101 Firefox/134.0"}, "ip": "192.168.1.131", "datetime": "Tue, 18 Feb 2025 19:28:15 -0000", "namespace": {"kind": "user", "name": "quayadmin", "avatar": {"name": "quayadmin", "hash": "6d640d802fe23b93779b987c187a4b7a4d8fbcbd4febe7009bdff58d84498fba", "color": "#f7b6d2", "kind": "user"}}}], "next_page": "gAAAAABntN-KbPJDI0PpcHmWjRCmQTLiCprE_KXiOSidbGZ7Ireu8pVTgGUIstijNhmiLzlAv_S3HOsCrKWnuBmoQYZ3F53Uxg=="}Use the
GET /api/v1/superuser/registrysize/endpoint to obtain information about the size of the registry:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ "https://<quay_server>/api/v1/superuser/registrysize/"Example output
{"size_bytes": 0, "last_ran": null, "running": false, "queued": false}Use the
POST /api/v1/superuser/registrysize/endpoint to define registry size information:$ curl -X POST "https://quay-server.example.com/api/v1/superuser/registrysize/" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "namespace": "<namespace>", "last_ran": 1700000000, "queued": true, "running": false }'This command does not return output in the CLI.
6.17.5. Managing organization quota with the Red Hat Quay API
To create, view, update, or delete organization quota policies in Red Hat Quay, you can use the superuser organization quota API endpoints.
Prerequisites
- You have created an OAuth access token.
- You are logged into your Red Hat Quay deployment as a superuser.
Procedure
Use the
POST /api/v1/superuser/organization/{namespace}/quotaAPI endpoint to create a quota policy for an organization:$ curl -X POST "https://quay-server.example.com/api/v1/superuser/organization/<namespace>/quota" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "limit_bytes": 10737418240 }'Example output
"Created"Use the
GET /api/v1/superuser/organization/{namespace}/quotaAPI endpoint to obtain information about the policy, including the quota ID:$ curl -X GET "https://quay-server.example.com/api/v1/superuser/organization/<namespace>/quota" \ -H "Authorization: Bearer <ACCESS_TOKEN>"Example output
[{"id": 2, "limit_bytes": 10737418240, "limit": "10.0 GiB", "default_config": false, "limits": [{"id": 1, "type": "Reject", "limit_percent": 90}], "default_config_exists": false}]Use the
PUT /api/v1/superuser/organization/{namespace}/quota/{quota_id}API endpoint to change the quota policy:$ curl -X PUT "https://quay-server.example.com/api/v1/superuser/organization/<namespace>/quota/<quota_id>" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "limit_bytes": <NEW_QUOTA_LIMIT> }'Example output
{"id": 2, "limit_bytes": 10737418240, "limit": "10.0 GiB", "default_config": false, "limits": [{"id": 1, "type": "Reject", "limit_percent": 90}], "default_config_exists": false}Use the
DELETE /api/v1/superuser/organization/{namespace}/quota/{quota_id}API endpoint to delete a quota policy for an organization:$ curl -X DELETE "https://quay-server.example.com/api/v1/superuser/organization/<namespace>/quota/<quota_id>" \ -H "Authorization: Bearer <ACCESS_TOKEN>"This command does not return output in the CLI.
6.17.6. Managing user quota with the Red Hat Quay API
To create, view, update, or delete user quota policies in Red Hat Quay, you can use the superuser user quota API endpoints.
Prerequisites
- You have created an OAuth access token.
- You are logged into your Red Hat Quay deployment as a superuser.
Procedure
Use the
POST /api/v1/superuser/users/{namespace}/quotaendpoint to create a quota policy for specific users within an organization:$ curl -X POST "https://quay-server.example.com/api/v1/superuser/users/<username>/quota" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "limit_bytes": <QUOTA_LIMIT> }'Example output
"Created"Use the
GET /api/v1/superuser/users/{namespace}/quotaendpoint to return a list of a user’s allotted quota:$ curl -X GET "https://quay-server.example.com/api/v1/superuser/users/<username>/quota" \ -H "Authorization: Bearer <ACCESS_TOKEN>"Example output
[{"id": 6, "limit_bytes": 10737418240, "limit": "10.0 GiB", "default_config": false, "limits": [], "default_config_exists": false}]Use the
PUT /api/v1/superuser/users/{namespace}/quota/{quota_id}endpoint to adjust the user’s policy:$ curl -X PUT "https://quay-server.example.com/api/v1/superuser/users/<username>/quota/<quota_id>" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "limit_bytes": <NEW_QUOTA_LIMIT> }'Example output
{"id": 6, "limit_bytes": 10737418240, "limit": "10.0 GiB", "default_config": false, "limits": [], "default_config_exists": false}Use the
DELETE /api/v1/superuser/users/{namespace}/quota/{quota_id}endpoint to delete a user’s policy:$ curl -X DELETE "https://quay-server.example.com/api/v1/superuser/users/<username>/quota/<quota_id>" \ -H "Authorization: Bearer <ACCESS_TOKEN>"This command does not return output in the CLI.
6.17.7. Retrieving build information with the Red Hat Quay API
To retrieve build details, status, and logs as a Red Hat Quay superuser, you can use the superuser build API endpoints.
Prerequisites
- You have created an OAuth access token.
- You have superuser privileges.
Procedure
Enter the following command to return information about a build by using the
GET /api/v1/superuser/{build_uuid}/buildendpoint:$ curl -X GET "https://quay-server.example.com/api/v1/superuser/<build_uuid>/build" \ -H "Authorization: Bearer <ACCESS_TOKEN>"Enter the following command to return the status for builds that you specify by UUID by using the
GET /api/v1/superuser/{build_uuid}/statusendpoint:$ curl -X GET "https://quay-server.example.com/api/v1/superuser/<build_uuid>/status" \ -H "Authorization: Bearer <ACCESS_TOKEN>"Enter the following command to return the build logs for a build that you specify by UUID by using the
GET /api/v1/superuser/{build_uuid}/logsendpoint:$ curl -X GET "https://quay-server.example.com/api/v1/superuser/<build_uuid>/logs" \ -H "Authorization: Bearer <ACCESS_TOKEN>"
6.17.8. Managing service keys as a superuser with the Red Hat Quay API
To create, list, approve, update, or delete service keys as a Red Hat Quay superuser, you can use the superuser keys API endpoints.
Prerequisites
- You have created an OAuth access token.
- You have superuser privileges.
Procedure
Enter the following command to create a service key by using the
POST /api/v1/superuser/keysendpoint:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{ "service": "<service_name>", "expiration": <unix_timestamp> }' \ "<quay_server>/api/v1/superuser/keys"Example output
{"message":""}Enter the following command to approve a service key by using the
POST /api/v1/superuser/approvedkeys/{kid}endpoint:$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{ "notes": "<approval_notes>" }' \ "https://<quay_server>/api/v1/superuser/approvedkeys/<kid>"This command does not return output in the CLI.
Enter the following command to list service keys by using the
GET /api/v1/superuser/keysendpoint:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ "https://<quay_server>/api/v1/superuser/keys"Example output
{"keys":[{"approval":{"approval_type":"ServiceKeyApprovalType.AUTOMATIC","approved_date":"Mon, 20 Jan 2025 14:46:01 GMT","approver":null,"notes":""},"created_date":"Mon, 20 Jan 2025 14:46:01 GMT","expiration_date":"Wed, 05 Feb 2025 22:03:37 GMT","jwk":{"e":"AQAB","kid":"<example>","kty":"RSA","n":"<example>"},"kid":"7fr8soqXGgea8JqjwgItjjJT9GKlt-bMyMCDmvzy6WQ","metadata":{"created_by":"CLI tool"},"name":"http://quay-server.example.com:80","rotation_duration":null,"service":"quay"}]}Enter the following command to return a list of service account keys by using the
GET /api/v1/superuser/apptokensendpoint:$ curl -X GET \ "https://quay-server.example.com/api/v1/superuser/apptokens" \ -H "Authorization: Bearer <superuser_access_token>" \ -H "Accept: application/json"Alternatively, you can include the
expiring=trueoption. For example:$ curl -X GET \ "https://quay-server.example.com/api/v1/superuser/apptokens?expiring=true" \ -H "Authorization: Bearer <superuser_access_token>" \ -H "Accept: application/json"Enter the following command to retrieve information about a service account by its kid by using the
GET /api/v1/superuser/keys/{kid}endpoint:$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ "https://<quay_server>/api/v1/superuser/keys/<kid>"Example output
{"approval":{"approval_type":"ServiceKeyApprovalType.AUTOMATIC","approved_date":"Mon, 20 Jan 2025 14:46:01 GMT","approver":null,"notes":""},"created_date":"Mon, 20 Jan 2025 14:46:01 GMT","expiration_date":"Wed, 05 Feb 2025 22:03:37 GMT","jwk":{"e":"AQAB","kid":"7fr8soqXGgea8JqjwgItjjJT9GKlt-bMyMCDmvzy6WQ","kty":"RSA","n":"5iMX7RQ_4F_zdb1qonMsuWUDauCOqEyRpD8L_EhgnwDxrgMHuOlJ4_7sEOrOa3Jkx3QhwIW6LJCP69PR5X0wvz6vmC1DoWEaWv41bAq23Knzj7gUU9-N_fkZPZN9NQwZ-D-Zqg9L1c_cJF93Dy93py8_JswWFDj1FxMaThJmrX68wBwjhF-JLYqgCAGFyezzJ3oTpO-esV9v6R7skfkaqtx_cjLZk_0cKB4VKTtxiy2A8D_5nANTOSSbZLXNh2Vatgh3yrOmnTTNLIs0YO3vFIuylEkczHlln-40UMAzRB3HNspUySyzImO_2yGdrA762LATQrOzJN8E1YKCADx5CQ"},"kid":"7fr8soqXGgea8JqjwgItjjJT9GKlt-bMyMCDmvzy6WQ","metadata":{"created_by":"CLI tool"},"name":"http://quay-server.example.com:80","rotation_duration":null,"service":"quay"}Enter the following command to update your service key, such as the metadata, by using the
PUT /api/v1/superuser/keys/{kid}endpoint:$ curl -X PUT \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{ "name": "<service_key_name>", "metadata": {"<key>": "<value>"}, "expiration": <unix_timestamp> }' \ "https://<quay_server>/api/v1/superuser/keys/<kid>"Example output
{"approval":{"approval_type":"ServiceKeyApprovalType.AUTOMATIC","approved_date":"Mon, 20 Jan 2025 14:46:01 GMT","approver":null,"notes":""},"created_date":"Mon, 20 Jan 2025 14:46:01 GMT","expiration_date":"Mon, 03 Mar 2025 10:40:00 GMT","jwk":{"e":"AQAB","kid":"7fr8soqXGgea8JqjwgItjjJT9GKlt-bMyMCDmvzy6WQ","kty":"RSA","n":"5iMX7RQ_4F_zdb1qonMsuWUDauCOqEyRpD8L_EhgnwDxrgMHuOlJ4_7sEOrOa3Jkx3QhwIW6LJCP69PR5X0wvz6vmC1DoWEaWv41bAq23Knzj7gUU9-N_fkZPZN9NQwZ-D-Zqg9L1c_cJF93Dy93py8_JswWFDj1FxMaThJmrX68wBwjhF-JLYqgCAGFyezzJ3oTpO-esV9v6R7skfkaqtx_cjLZk_0cKB4VKTtxiy2A8D_5nANTOSSbZLXNh2Vatgh3yrOmnTTNLIs0YO3vFIuylEkczHlln-40UMAzRB3HNspUySyzImO_2yGdrA762LATQrOzJN8E1YKCADx5CQ"},"kid":"7fr8soqXGgea8JqjwgItjjJT9GKlt-bMyMCDmvzy6WQ","metadata":{"created_by":"CLI tool","environment":"production"},"name":"quay-service-key-updated","rotation_duration":null,"service":"quay"}Enter the following command to delete a service key by using the
DELETE /api/v1/superuser/keys/{kid}endpoint:$ curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ "https://<quay_server>/api/v1/superuser/keys/<kid>"This command does not return output in the CLI.
6.18. Managing tags with the Red Hat Quay API
To change, restore, list, or delete repository tags in Red Hat Quay, you can use the tag API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
PUT /api/v1/repository/{repository}/tag/{tag}endpoint to change which image a tag points to or create a new tag:$ curl -X PUT "https://quay-server.example.com/api/v1/repository/<namespace>/<repo_name>/tag/<tag_name>" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Content-Type: application/json" \ -d '{"manifest_digest": "<MANIFEST_DIGEST>"}'Example output
"Updated"Use the
POST /api/v1/repository/{repository}/tag/{tag}/restoreendpoint to restore a repository tag back to a previous image in the repository:$ curl -X POST "https://quay-server.example.com/api/v1/repository/<namespace>/<repo_name>/tag/<tag_name>/restore" \ -H "Authorization: Bearer <your_access_token>" \ -H "Content-Type: application/json" \ -d '{"manifest_digest": "sha256:<your_manifest_digest>"}'Example output
{}Use the
GET /api/v1/repository/{repository}/tag/endpoint to obtain a list of repository tags:$ curl -X GET "https://quay-server.example.com/api/v1/repository/<namespace>/<repo_name>/tag/" \ -H "Authorization: Bearer <your_access_token>" \ -H "Content-Type: application/json"Example output
{"tags": [{"name": "test", "reversion": true, "start_ts": 1740496373, "manifest_digest": "sha256:d08334991a3dba62307016833083d6433f489ab0f7d36d0a4771a20b4569b2f6", "is_manifest_list": false, "size": 2280303, "last_modified": "Tue, 25 Feb 2025 15:12:53 -0000"}, {"name": "test", "reversion": false, "start_ts": 1740495442, "end_ts": 1740496373, "manifest_digest": "sha256:d08334991a3dba62307016833083d6433f489ab0f7d36d0a4771a20b4569b2f6", "is_manifest_list": false, "size": 2280303, "last_modified": "Tue, 25 Feb 2025 14:57:22 -0000", "expiration": "Tue, 25 Feb 2025 15:12:53 -0000"}, {"name": "test", "reversion": false, "start_ts": 1740495408, "end_ts": 1740495442, "manifest_digest": "sha256:d08334991a3dba62307016833083d6433f489ab0f7d36d0a4771a20b4569b2f6", "is_manifest_list": false, "size": 2280303, "last_modified": "Tue, 25 Feb 2025 14:56:48 -0000", "expiration": "Tue, 25 Feb 2025 14:57:22 -0000"}], "page": 1, "has_additional": false}Use the
DELETE /api/v1/repository/{repository}/tag/{tag}endpoint to delete a tag from a repository:$ curl -X DELETE "https://quay-server.example.com/api/v1/repository/<namespace>/<repo_name>/tag/<tag_name>" \ -H "Authorization: Bearer <your_access_token>"This command does not return output in the CLI.
6.19. Managing teams by using the API
Organization teams in Red Hat Quay group users for shared repository access. You can manage teams and membership by using the API.
6.19.1. Managing team members and repository permissions by using the API
To add, invite, or remove members of an organization team in Red Hat Quay, you can use the team member API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Enter the
PUT /api/v1/organization/{orgname}/team/{teamname}/members/{membername}command to add or invite a member to an existing team:$ curl -X PUT \ -H "Authorization: Bearer <your_access_token>" \ "<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>/members/<member_name>"Example output
{"name": "testuser", "kind": "user", "is_robot": false, "avatar": {"name": "testuser", "hash": "d51d17303dc3271ac3266fb332d7df919bab882bbfc7199d2017a4daac8979f0", "color": "#5254a3", "kind": "user"}, "invited": false}Enter the
DELETE /api/v1/organization/{orgname}/team/{teamname}/members/{membername}command to remove a member of a team:$ curl -X DELETE \ -H "Authorization: Bearer <your_access_token>" \ "<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>/members/<member_name>"This command does not return output in the CLI. To ensure that a member has been deleted, you can enter the
GET /api/v1/organization/{orgname}/team/{teamname}/memberscommand and ensure that the member is not returned in the output.$ curl -X GET \ -H "Authorization: Bearer <your_access_token>" \ "<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>/members"Example output
{"name": "owners", "members": [{"name": "quayadmin", "kind": "user", "is_robot": false, "avatar": {"name": "quayadmin", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}, "invited": false}, {"name": "test-org+test", "kind": "user", "is_robot": true, "avatar": {"name": "test-org+test", "hash": "aa85264436fe9839e7160bf349100a9b71403a5e9ec684d5b5e9571f6c821370", "color": "#8c564b", "kind": "robot"}, "invited": false}], "can_edit": true}You can enter the
PUT /api/v1/organization/{orgname}/team/{teamname}/invite/{email}command to invite a user, by email address, to an existing team:$ curl -X PUT \ -H "Authorization: Bearer <your_access_token>" \ "<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>/invite/<email>"You can enter the
DELETE /api/v1/organization/{orgname}/team/{teamname}/invite/{email}command to delete the invite of an email address to join a team. For example:$ curl -X DELETE \ -H "Authorization: Bearer <your_access_token>" \ "<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>/invite/<email>"
6.19.2. Setting the role of a team within an organization by using the API
To view repository permissions for a team or set a team’s role in an Red Hat Quay organization, you can use the organization team API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Enter the following
GET /api/v1/organization/{orgname}/team/{teamname}/permissionscommand to return a list of repository permissions for the organization’s team. Note that your team must have been added to a repository for this command to return information.$ curl -X GET \ -H "Authorization: Bearer <your_access_token>" \ "<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>/permissions"Example output
{"permissions": [{"repository": {"name": "api-repo", "is_public": true}, "role": "admin"}]}You can create or update a team within an organization to have a specified role of admin, member, or creator using the
PUT /api/v1/organization/{orgname}/team/{teamname}command. For example:$ curl -X PUT \ -H "Authorization: Bearer <your_access_token>" \ -H "Content-Type: application/json" \ -d '{ "role": "<role>" }' \ "<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>"Example output
{"name": "testteam", "description": "", "can_view": true, "role": "creator", "avatar": {"name": "testteam", "hash": "827f8c5762148d7e85402495b126e0a18b9b168170416ed04b49aae551099dc8", "color": "#ff7f0e", "kind": "team"}, "new_team": false}
6.19.3. Deleting a team within an organization by using the API
To delete a team from an organization in Red Hat Quay, you can use the organization team API endpoint with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
You can delete a team within an organization by entering the
DELETE /api/v1/organization/{orgname}/team/{teamname}command:$ curl -X DELETE \ -H "Authorization: Bearer <your_access_token>" \ "<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>"This command does not return output in the CLI.
6.20. Managing builds by using the Red Hat Quay API
To list, activate, start, update, or delete build triggers in Red Hat Quay, you can use the build trigger API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
GET /api/v1/repository/{repository}/trigger/endpoint to list the triggers for the specified repository:$ curl -X GET "https://quay-server.example.com/api/v1/repository/example_namespace/example_repo/trigger/" \ -H "Authorization: Bearer <your_access_token>"Example output
{"triggers": [{"id": "32ca5eae-a29f-46c7-8f44-3221ca417c92", "service": "custom-git", "is_active": false, "build_source": null, "repository_url": null, "config": {}, "can_invoke": true, "enabled": true, "disabled_reason": null}]}Use the
POST /api/v1/repository/{repository}/trigger/{trigger_uuid}/activateendpoint to activate the specified build trigger.$ curl -X POST "https://quay-server.example.com/api/v1/repository/example_namespace/example_repo/trigger/example-trigger-uuid/activate" \ -H "Authorization: Bearer <your_access_token>" \ -H "Content-Type: application/json" \ -d '{ "config": { "branch": "main" }, "pull_robot": "example+robot" }'Use the
POST /api/v1/repository/{repository}/trigger/{trigger_uuid}/startendpoint to manually start the build from the specified trigger:$ curl -X POST "https://quay-server.example.com/api/v1/repository/example_namespace/example_repo/trigger/example-trigger-uuid/start" \ -H "Authorization: Bearer <your_access_token>" \ -H "Content-Type: application/json" \ -d '{ "branch_name": "main", "commit_sha": "abcdef1234567890", "refs": "refs/heads/main" }'Use the
GET /api/v1/repository/{repository}/trigger/{trigger_uuid}/buildsendpoint to list the builds started by the specified trigger:$ curl -X GET "https://quay-server.example.com/api/v1/repository/example_namespace/example_repo/trigger/example-trigger-uuid/builds?limit=10" \ -H "Authorization: Bearer <your_access_token>"Use the
GET /api/v1/repository/{repository}/trigger/{trigger_uuid}endpoint to get information for the specified build trigger:$ curl -X GET "https://quay-server.example.com/api/v1/repository/example_namespace/example_repo/trigger/example-trigger-uuid" \ -H "Authorization: Bearer <your_access_token>"Use the
PUT /api/v1/repository/{repository}/trigger/{trigger_uuid}endpoint to update the specified build trigger:$ curl -X PUT "https://quay-server.example.com/api/v1/repository/example_namespace/example_repo/trigger/example-trigger-uuid" \ -H "Authorization: Bearer <your_access_token>" \ -H "Content-Type: application/json" \ -d '{"enabled": true}'Use the
DELETE /api/v1/repository/{repository}/trigger/{trigger_uuid}endpoint to delete the specified build trigger:$ curl -X DELETE "https://quay-server.example.com/api/v1/repository/example_namespace/example_repo/trigger/example-trigger-uuid" \ -H "Authorization: Bearer <your_access_token>"
6.21. Managing current user options by using the Red Hat Quay API
To retrieve account information or star and unstar repositories in Red Hat Quay, you can use the user API endpoints with an OAuth access token.
Prerequisites
- You have created an OAuth access token.
Procedure
Use the
GET /api/v1/user/endpoint to get user information for the authenticated user.$ curl -X GET "https://quay-server.example.com/api/v1/user/" \ -H "Authorization: Bearer <your_access_token>"Example output
{"anonymous": false, "username": "quayadmin", "avatar": {"name": "quayadmin", "hash": "6d640d802fe23b93779b987c187a4b7a4d8fbcbd4febe7009bdff58d84498fba", "color": "#f7b6d2", "kind": "user"}, "can_create_repo": true, "is_me": true, "verified": true, "email": "test@gmil.com", "logins": [], "invoice_email": false, "invoice_email_address": null, "preferred_namespace": false, "tag_expiration_s": 1209600, "prompts": [], "company": null, "family_name": null, "given_name": null, "location": null, "is_free_account": true, "has_password_set": true, "quotas": [{"id": 4, "limit_bytes": 2199023255552, "limits": [{"id": 3, "type": "Reject", "limit_percent": 100}]}], "quota_report": {"quota_bytes": 2280675, "configured_quota": 2199023255552, "running_backfill": "complete", "backfill_status": "complete"}, "organizations": [{"name": "test", "avatar": {"name": "test", "hash": "a15d479002b20f211568fd4419e76686d2b88a4980a5b4c4bc10420776c5f6fe", "color": "#aec7e8", "kind": "org"}, "can_create_repo": true, "public": false, "is_org_admin": true, "preferred_namespace": false}, {"name": "sample", "avatar": {"name": "sample", "hash": "ba560c68f1d26e8c6b911ac9b5d10d513e7e43e576cc2baece1b8a46f36a29a5", "color": "#b5cf6b", "kind": "org"}, "can_create_repo": true, "public": false, "is_org_admin": true, "preferred_namespace": false}], "super_user": true}Use the
GET /api/v1/users/{username}endpoint to get user information for the specified user.$ curl -X GET "https://quay-server.example.com/api/v1/users/example_user" \ -H "Authorization: Bearer <your_access_token>"Example output
{"anonymous": false, "username": "testuser", "avatar": {"name": "testuser", "hash": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "color": "#6b6ecf", "kind": "user"}, "super_user": false}Use the
POST /api/v1/user/starredendpoint to star a repository:$ curl -X POST "https://quay-server.example.com/api/v1/user/starred" \ -H "Authorization: Bearer <your_access_token>" \ -H "Content-Type: application/json" \ -d '{ "namespace": "<namespace>", "repository": "<repository_name>" }'Example output
{"namespace": "test", "repository": "testrepo"}Use the
GET /api/v1/user/starredendpoint to list all starred repositories:$ curl -X GET "https://quay-server.example.com/api/v1/user/starred?next_page=<next_page_token>" \ -H "Authorization: Bearer <your_access_token>"Example output
{"repositories": [{"namespace": "test", "name": "testrepo", "description": "This repository is now under maintenance.", "is_public": true}]}Use the
DELETE /api/v1/user/starred/{repository}endpoint to delete a star from a repository:$ curl -X DELETE "https://quay-server.example.com/api/v1/user/starred/namespace/repository-name" \ -H "Authorization: Bearer <your_access_token>"This command does not return output in the CLI.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}