Red Hat Quay API guide

Red Hat Quay 3

Red Hat Quay API Guide

Red Hat OpenShift Documentation Team

Abstract

Use the Red Hat Quay API

Preface

The Red Hat Quay application programming interface (API) provides a comprehensive, RESTful interface for managing and automating tasks within Red Hat Quay. Designed around the OAuth 2.0 protocol, this API enables secure, fine-grained access to Red Hat Quay resources, and allows administrators and users to perform such actions as creating repositories, managing images, setting permissions, and more.

Red Hat Quay follows Semantic Versioning (SemVer) principles, ensuring predictable API stability across releases, such as:

Major releases: Introduce new capabilities. Might include breaking changes to API compatibility. For example, the API of Red Hat Quay 2.0 differs from Red Hat Quay 3.0.
Minor releases: Add new functionality in a backward-compatible manner. For example, a 3.y release adds functionality to the version 3. release.
Patch releases: Deliver bug fixes and improvements while preserving backward compatibility with minor releases, such as 3.y.z.

The following guide describes the Red Hat Quay API in more detail, and provides details on the following topics:

OAuth 2 access tokens and how they compare to traditional API tokens and Red Hat Quay’s robot tokens
Generating an OAuth 2 access token
Best practices for token management
OAuth 2 access token capabilities
Using the Red Hat Quay API
Red Hat Quay API configuration examples

This guide is accompanied with a second guide, Red Hat Quay API reference, that provides information about all api/v1 endpoints and how to access those endpoints with example commands.

Chapter 1. Introduction to Red Hat Quay OAuth 2.0 tokens

The Red Hat Quay OAuth 2 token system provides a secure, standards-based method for accessing Red Hat Quay’s API and other relevant resources. The OAuth 2 token-based approach provides a secure method for handling authentication and authorization for complex environments. Compared to more traditional API tokens, Red Hat Quay’s OAuth 2 token system offers the following enhancements:

Standards-based security, which adheres to the OAuth 2.0 protocol.
Revocable access by way of deleting the application in which the OAuth 2 token exists.
Fine-grained access control, which allows Red Hat Quay administrators the ability to assign specific permissions to tokens.
Delegated access, which allows third-party applications and services to act on behalf of a user.
Future-proofing, which helps ensure that Red Hat Quay remains compatible with other services, platforms, and integrations.

Red Hat Quay primarily supports two types of tokens: OAuth 2 access tokens and robot account tokens. A third token type, an OCI referrers access token, that is required to list OCI referrers of a manifest under a repository, is also available when warranted.

The following chapters provide more details about each token type and how to generate each token type.

Chapter 2. OAuth 2 access tokens

OAuth 2 access tokens (considered "API tokens" for Red Hat Quay) enable user-authenticated access to the Red Hat Quay API, suitable for applications that require user identity verification. These tokens are obtained through an OAuth 2 authorization process, where a Red Hat Quay administrator generates a token on behalf of themselves or another user to access Red Hat Quay API endpoints. OAuth 2 tokens authorize actions on API endpoints based on the scopes defined for the token.

Note

Although OAuth 2 tokens authorize actions on API endpoints based on the scopes defined for the token, access to the resources themselves is governed by Red Hat Quay’s role-based access control (RBAC) mechanisms. Actions can be created on a resource, for example, a repository, provided that you have the proper role (Admin or Creator) to do so for that namespace. This is true even if the API token was granted the repo:admin scope.

OAuth 2 access tokens can only be created by using the Red Hat Quay UI; there is no way to create an OAuth 2 access token by using the CLI. When creating an OAuth 2 token, the following options can be selected for a token holder:

Administer Organization. When selected, allows the user to be able to administer organizations, including creating robots, creating teams, adjusting team membership, and changing billing settings.
Administer Repositories. When selected, provides the user administrator access to all repositories to which the granting user has access.
Create Repositories. When selected, provides the user the ability to create repositories in any namespaces that the granting user is allowed to create repositories.
View all visible repositories. When selected, provides the user the ability to view and pull all repositories visible to the granting user.
Read/Write to any accessible repositories. When selected, provides the user the ability to view, push and pull to all repositories to which the granting user has write access.
Super User Access. When selected, provides the user the ability to administer your installation including managing users, managing organizations and other features found in the superuser panel.
Administer User When selected, provides the user the ability to administer your account including creating robots and granting them permissions to your repositories.
Read User Information. When selected, provides the user the ability to read user information such as username and email address.

Token distributors should be mindful of the permissions that they are granting when generating a token on behalf of a user, and should have absolute trust in a user before granting such permissions as Administer organization, Super User Access, and Administer User. Additionally, the access token is only revealed at the time of creation; they cannot be listed from the CLI, nor can they be found on the Red Hat Quay UI. If an access token is lost or forgotten, a new token must be created; a token cannot be recovered.

OAuth 2 access tokens are passed as a Bearer token in the Authorization header of an API call and, as a result, are used to provide authentication and authorization to the defined API endpoint, such as an image tag, a repository, an organization, and so on.

The API is available from the /api/v1 endpoint of your Red Hat Quay host. For example, https://<quay-server.example.com>/api/v1. It allows users to connect to endpoints through their browser to GET, POST, DELETE, and PUT Red Hat Quay settings by enabling the Swagger UI. The API can be accessed by applications that make API calls and use OAuth tokens, and it sends and receives data as JSON.

With Red Hat Quay, there is currently no way to rotate or to set an expiration time on an OAuth 2 access token, and the token lifespan is 10 years. Tokens can be deleted by deleting the applications in which they were created in the event that they are compromised, however, this deletes all tokens that were made within that specific application.

Note

In practice, Red Hat Quay administrators could create a new OAuth application on the Applications page of their organization each time they wanted to create a new OAuth token for a user. This would ensure that a single application is not responsible for all OAuth tokens. As a result, in the event that a user’s token is compromised, the administrator would delete the application of the compromised token. This would help avoid disruption for other users whose tokens might be part of the same application.

The following sections shows you how to generate and reassign an OAuth 2 access token.

2.1. Creating an OAuth 2 access token

With Red Hat Quay, you must create an OAuth 2 access token before you can access the API endpoints of your organization. OAuth 2 access token can only be generated by using the Red Hat Quay UI; the CLI cannot be used to generate an OAuth 2 access token.

Use the following procedure to create an OAuth2 access token.

Prerequisites

You have logged in to Red Hat Quay as an administrator.
You have created an OAuth 2 application.

Procedure

On the main page, select an Organization.
In the navigation pane, select Applications.
Click the name of your application, for example, Test application.
In the navigation pane, select Generate Token.
Check the boxes for the following options:
1. Administer Organization. When selected, allows the user to be able to administer organizations, including creating robots, creating teams, adjusting team membership, and changing billing settings.
2. Administer Repositories. When selected, provides the user administrator access to all repositories to which the granting user has access.
3. Create Repositories. When selected, provides the user the ability to create repositories in any namespaces that the granting user is allowed to create repositories.
4. View all visible repositories. When selected, provides the user the ability to view and pull all repositories visible to the granting user.
5. Read/Write to any accessible repositories. When selected, provides the user the ability to view, push and pull to all repositories to which the granting user has write access.
6. Super User Access. When selected, provides the user the ability to administer your installation including managing users, managing organizations and other features found in the superuser panel.
7. Administer User When selected, provides the user the ability to administer your account including creating robots and granting them permissions to your repositories.
8. Read User Information. When selected, provides the user the ability to read user information such as username and email address.
Click Generate Access Token. You are redirected to a new page.
Review the permissions that you are allowing, then click Authorize Application. Confirm your decision by clicking Authorize Application.
You are redirected to the Access Token page. Copy and save the access token.
Important
This is the only opportunity to copy and save the access token. It cannot be reobtained after leaving this page.

2.2. Reassigning an OAuth access token

Organization administrators can assign OAuth API tokens to be created by other user’s with specific permissions. This allows the audit logs to be reflected accurately when the token is used by a user that has no organization administrative permissions to create an OAuth API token.

Note

The following procedure only works on the current Red Hat Quay UI. It is not currently implemented in the Red Hat Quay v2 UI.

Prerequisites

You are logged in as a user with organization administrative privileges, which allows you to assign an OAuth API token.
Note
OAuth API tokens are used for authentication and not authorization. For example, the user that you are assigning the OAuth token to must have the Admin team role to use administrative API endpoints. For more information, see Managing access to repositories.

Procedure

Optional. If not already, update your Red Hat Quay config.yaml file to include the FEATURE_ASSIGN_OAUTH_TOKEN: true field:
```
# ...
FEATURE_ASSIGN_OAUTH_TOKEN: true
# ...
```
Optional. Restart your Red Hat Quay registry.
Log in to your Red Hat Quay registry as an organization administrator.
Click the name of the organization in which you created the OAuth token for.
In the navigation pane, click Applications.
Click the proper application name.
In the navigation pane, click Generate Token.
Click Assign another user and enter the name of the user that will take over the OAuth token.
Check the boxes for the desired permissions that you want the new user to have. For example, if you only want the new user to be able to create repositories, click Create Repositories.
Important
Permission control is defined by the team role within an organization and must be configured regardless of the options selected here. For example, the user that you are assigning the OAuth token to must have the Admin team role to use administrative API endpoints.
Solely checking the Super User Access box does not actually grant the user this permission. Superusers must be configured via the config.yaml file and the box must be checked here.
Click Assign token. A popup box appears that confirms authorization with the following message and shows you the approved permissions:
```
This will prompt user <username> to generate a token with the following permissions:
repo:create
```
Click Assign token in the popup box. You are redirected to a new page that displays the following message:
```
Token assigned successfully
```

Verification

After reassigning an OAuth token, the assigned user must accept the token to receive the bearer token, which is required to use API endpoints. Request that the assigned user logs into the Red Hat Quay registry.
After they have logged in, they must click their username under Users and Organizations.
In the navigation pane, they must click External Logins And Applications.
Under Authorized Applications, they must confirm the application by clicking Authorize Application. They are directed to a new page where they must reconfirm by clicking Authorize Application.
They are redirected to a new page that reveals their bearer token. They must save this bearer token, as it cannot be viewed again.

2.3. Deleting an OAuth 2 access token

Because OAuth 2 access tokens are created through the OAuth application, they cannot be rotated or renewed. In the event that a token is compromised, or you need to delete a token, you must deleted its associated application through the Red Hat Quay UI.

Important

Deleting an application deletes all tokens that were made within that specific application. Use with caution.

Prerequisites

You have created an OAuth 2 access token.

Procedure

On the Red Hat Quay UI, click the name of the organization hosting the application. Then, in the navigation pane, click Applications.
Click the application name, for example, Test application.
In the navigation pane, click Delete Application. You are redirected to a new page. Click Delete application and confirm your decision.

Chapter 3. Robot account tokens

Robot account tokens are password-type credentials used to access a Red Hat Quay registry via normal Docker v2 endpoints; these are defined as tokens on the UI because the password itself is encrypted.

Robot account tokens are persistent tokens designed for automation and continuous integration workflows. By default, Red Hat Quay’s robot account tokens do not expire and do not require user interaction, which makes robot accounts ideal for non-interactive use cases.

Robot account tokens are automatically generated at the time of a robot’s creation and are non-user specific; that is, they are connected to the user and organization namespace where where they are created. for example, a robot named project_tools+<robot_name> is associated with the project_tools namespace.

Robot account tokens provide access without needing a user’s personal credentials. How the robot account is configured, for example, with one of READ, WRITE, or ADMIN permissions, ultimately defines the actions that the robot account can take.

Because robot account tokens are persistent and do not expire by default, they are ideal for automated workflows that require consistent access to Red Hat Quay without manual renewal. Despite this, robot account tokens can be easily re-generated by using the the UI. They can also be regenerated by using the proper API endpoint via the CLI. To enhance the security of your Red Hat Quay deployment, administrators should regularly refresh robot account tokens. Additionally, with the keyless authentication with robot accounts feature, robot account tokens can be exchanged for external OIDC tokens and leveraged so that they only last one hour, enhancing the security of your registry.

When a namespace gets deleted, or when the robot account is deleted itself, they are garbage collected when the collector is scheduled to run.

The following section shows you how to use the API to re-generate a robot account token for organization robots and user robots.

3.1. Regenerating a robot account token by using the Red Hat Quay UI

Use the following procedure to regenerate a robot account token by using the Red Hat Quay UI.

Prerequisites

You have logged into Red Hat Quay.

Procedure

Click the name of an Organization.
In the navigation pane, click Robot accounts.
Click the name of your robot account, for example, testorg3+test.
Click Regenerate token in the popup box.

3.2. Regenerating a robot account token by using the Red Hat Quay API

Use the following procedure to regenerate a robot account token using the Red Hat Quay API.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

Enter the following command to regenerate a robot account token for an organization using the POST /api/v1/organization/{orgname}/robots/{robot_shortname}/regenerate endpoint:

$ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  "<quay-server.example.com>/api/v1/organization/<orgname>/robots/<robot_shortname>/regenerate"

Example output

{"name": "test-org+test", "created": "Fri, 10 May 2024 17:46:02 -0000", "last_accessed": null, "description": "", "token": "<example_secret>"}

Enter the following command to regenerate a robot account token for the current user with the POST /api/v1/user/robots/{robot_shortname}/regenerate endpoint:

$ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  "<quay-server.example.com>/api/v1/user/robots/<robot_shortname>/regenerate"

Example output

{"name": "quayadmin+test", "created": "Fri, 10 May 2024 14:12:11 -0000", "last_accessed": null, "description": "", "token": "<example_secret>"}

Chapter 4. OCI referrers OAuth access token

In some cases, depending on the features that your Red Hat Quay deployment is configured to use, you might need to leverage an OCI referrers OAuth access token. OCI referrers OAuth access tokens are used to list OCI referrers of a manifest under a repository, and uses a curl command to make a GET request to the Red Hat Quay v2/auth endpoint.

These tokens are obtained via basic HTTP authentication, wherein the user provides a username and password encoded in Base64 to authenticate directly with the v2/auth API endpoint. As such, they are based directly on the user’s credentials aod do not follow the same detailed authorization flow as OAuth 2, but still allow a user to authorize API requests.

OCI referrers OAuth access tokens do not offer scope-based permissions and do not expire. They are solely used to list OCI referrers of a manifest under a repository.

Additional resource

Attaching referrers to an image tag

4.1. Creating an OCI referrers OAuth access token

This OCI referrers OAuth access token is used to list OCI referrers of a manifest under a repository.

Procedure

Update your config.yaml file to include the FEATURE_REFERRERS_API: true field. For example:
```
# ...
FEATURE_REFERRERS_API: true
# ...
```
Enter the following command to Base64 encode your credentials:
```
$ echo -n '<username>:<password>' | base64
```
Example output
```
abcdeWFkbWluOjE5ODlraWROZXQxIQ==
```

Enter the following command to use the base64 encoded string and modify the URL endpoint to your Red Hat Quay server:

$ curl --location '<quay-server.example.com>/v2/auth?service=<quay-server.example.com>&scope=repository:quay/listocireferrs:pull,push' --header 'Authorization: Basic <base64_username:password_encode_token>' -k | jq

Example output

{
  "token": "<example_secret>
}

Chapter 5. Enabling and using the Red Hat Quay API

By leveraging the Red Hat Quay API, you can streamline container registry management, automate tasks, and integrate Red Hat Quay’s functionalities into your existing workflow. This can improve efficiency, offer enhanced flexibility (by way of repository management, user management, user permissions, image management, and so on), increase the stability of your organization, repository, or overall deployment, and more.

The following sections explain how to enable and use the Red Hat Quay API.

5.1. Configuring Red Hat Quay to accept API calls

Prior to using the Red Hat Quay API, you must disable BROWSER_API_CALLS_XHR_ONLY in your config.yaml file. This allows you to avoid such errors as API calls must be invoked with an X-Requested-With header if called from a browser.

Procedure

In your Red Hat Quay config.yaml file, set BROWSER_API_CALLS_XHR_ONLY to false. For example:
```
# ...
BROWSER_API_CALLS_XHR_ONLY: false
# ...
```
Restart your Red Hat Quay deployment.

5.2. Using the Red Hat Quay API

After you have created an application and generated an OAuth 2 access token with the desired settings, you can pass in the access token to GET, PUT, POST, or DELETE settings by using the API from the CLI. Generally, a Red Hat Quay API command looks similar to the following example:

$ curl -X GET -H "Authorization: Bearer <your_access_token>" \ 1
    https://<quay-server.example.com>/api/v1/<example>/<endpoint>/ 2

1: The OAuth 2 access token that was generated through the Red Hat Quay UI.
2: The URL of your Red Hat Quay deployment and the desired API endpoint.

All Red Hat Quay APIs are documented in the Application Programming Interface (API) chapter. Understanding how they are documented is crucial to successful invocation. Take, for example, the following entry for the createAppToken API endpoint:

*createAppToken* 1
Create a new app specific token for user. 2

*POST /api/v1/user/apptoken* 3

**Authorizations: **oauth2_implicit (**user:admin**) 4

 Request body schema (application/json)

*Path parameters* 5

Name: **title**
Description: Friendly name to help identify the token.
Schema: string

*Responses* 6

|HTTP Code|Description             |Schema
|201      |Successful creation     |
|400      |Bad Request             |&lt;&lt;_apierror,ApiError&gt;&gt;
|401      |Session required        |&lt;&lt;_apierror,ApiError&gt;&gt;
|403      |Unauthorized access     |&lt;&lt;_apierror,ApiError&gt;&gt;
|404      |Not found               |&lt;&lt;_apierror,ApiError&gt;&gt;
|===

1: The name of the API endpoint.
2: A brief description of the API endpoint.
3: The API endpoint used for invocation.
4: The authorizations required to use the API endpoint.
5: The available paths to be used with the API endpoint. In this example, title is the only path to be used with the POST /api/v1/user/apptoken endpoint.
6: The API responses for this endpoint.

In order to use an API endpoint, you pass in your access token and then include the appropriate fields depending on your needs. The following procedure shows you how to use the POST /api/v1/user/apptoken endpoint.

Prerequisites

You have access to the Red Hat Quay API, which entails having already created an OAuth 2 access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

Create a user application by entering the POST /api/v1/user/apptoken API call:

$ curl -X POST \
  -H "Authorization: Bearer <access_token>" 1
  -H "Content-Type: application/json" \
  -d '{
    "title": "MyAppToken" 2
  }' \
  "http://quay-server.example.com/api/v1/user/apptoken" 3

1: The Oauth access token.
2: The name of your application token.
3: The URL of your Red Hat Quay deployment appended with the /api/v1/user/apptoken endpoint.

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": "K2YQB1YO0ABYV5OBUYOMF9MCUABN12Y608Q9RHFXBI8K7IE8TYCI4WEEXSVH1AXWKZCKGUVA57PSA8N48PWED9F27PXATFUVUD9QDNCE9GOT9Q8ACYPIN0HL"}}

Verification

On the Red Hat Quay UI, click your username in the navigation pane → Account Settings. The name of your application appears under the Docker CLI and other Application Tokens heading. For example:

5.3. Accessing Red Hat Quay Swagger UI

Red Hat Quay administrators and users can interacting with the API by using the Swagger UI-an interactive web interface that compiles executable commands. The Swagger UI can be launched as a container that points to your Red Hat Quay instance’s API discovery endpoint (/api/v1/discovery). After deploying the container, you can access the Swagger UI, which loads the OpenAPI specification for Red Hat Quay from the specified URL. Red Hat Quay administrators and users can explore the available endpoints and their structure.

Use the following procedure to access the Red Hat Quay Swagger UI.

Procedure

Enter the following command to deploy the Swagger UI container, pointing the URL to your Red Hat Quay’s API discovery endpoint. For example:

$ podman run -p 8080:8080 -e SWAGGER_JSON_URL=<quay-server.example.com> docker.swagger.io/swaggerapi/swagger-ui

Example output

---
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
20-envsubst-on-templates.sh: Running envsubst on /etc/nginx/templates/default.conf.template to /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/40-swagger-ui.sh
/docker-entrypoint.sh: Configuration complete; ready for start up
---

Navigate to the localhost URL. In this example, it is http://localhost:8080/.
Use the Swagger UI to test various API endpoints. For example, to create a new token for a user, you can click the POST /api/v1/user/apptoken endpoint → Try it out → Execute to generate an example curl command.
Note
Currently, server responses cannot be generated. This is because the Swagger UI is not set up to accept bearer tokens. As a result, the following error is returned for each command: {"error": "CSRF token was invalid or missing."}. As a workaround, you can copy this command into your terminal and manually add your bearer token, for example, -H 'Authorization: Bearer <bearer_token>'

5.4. Automating Red Hat Quay processes by using the API

With the API, Red Hat Quay administrators and users with access to the API can automate repetitive tasks such as repository management or image pruning.

The following example shows you how you might use a Python script and a cron job to automate the deletion of OAuth 2 applications except the administrator’s token. This might be useful if you want to ensure an application associated with an OAuth 2 access token is cycled after a certain period of time.

Prerequisites

You have access to the Red Hat Quay API, which entails having already created an OAuth 2 access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.
You have installed the Python requests library using.
You have enabled cron jobs on your machine.
You have created several organization applications, including one that will not be deleted.

Procedure

Create a Python script that executes an API command. The following example is used to delete organization applications using the DELETE /api/v1/organization/{orgname}/applications/{client_id} API endpoint.

example.py file

import requests 1

# Hard-coded values
API_BASE_URL = "http://<quay-server.example.com>/api/v1" 2
ACCESS_TOKEN = "<access_token>" 3
ORG_NAME = "<organization_name>" 4

def get_all_organization_applications():
    url = f"{API_BASE_URL}/organization/{ORG_NAME}/applications"
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}"
    }

    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        try:
            applications = response.json()
            # Print the raw response for debugging
            print("Raw response:", applications)

            # Adjust parsing logic based on the response structure
            if isinstance(applications, dict) and 'applications' in applications:
                applications = applications['applications']

            if isinstance(applications, list):
                print("Organization applications retrieved successfully:")
                for app in applications:
                    # Updated key from 'title' to 'name'
                    print(f"Name: {app['name']}, Client ID: {app['client_id']}")
                return applications
            else:
                print("Unexpected response format.")
                return []
        except requests.exceptions.JSONDecodeError:
            print("Error decoding JSON response:", response.text)
            return []
    else:
        print(f"Failed to retrieve applications. Status code: {response.status_code}, Response: {response.text}")
        return []

def delete_organization_application(client_id):
    url = f"{API_BASE_URL}/organization/{ORG_NAME}/applications/{client_id}"
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}"
    }

    response = requests.delete(url, headers=headers)

    if response.status_code == 204:
        print(f"Application {client_id} deleted successfully.")
    else:
        print(f"Failed to delete application {client_id}. Status code: {response.status_code}, Response: {response.text}")

def main():
    applications = get_all_organization_applications()
    for app in applications:
        if app['name'] != "<admin_token_app>": <5>  # Skip the "admin-token-app"
            delete_organization_application(app['client_id'])
        else:
            print(f"Skipping deletion of application: {app['name']}")

# Execute the main function
main()

1: Includes the import library in your Python code.
2: The URL of your registry appended with /api/v1.
3: Your OAuth 2 access token.
4: The organization that holds the application.
: The name of the application token to remain.

Save the script as prune_applications.py.
Create a cron job that automatically runs the script:
1. Open the crontab editor by running the following command:
```
$ crontab -e
```
2. In the editor, add the cron job for running the script. The following example runs the script once per month:
```
0 0 1 * * sudo python /path/to/prune_images.py >> /var/log/prune_images.log 2>&1
```

Chapter 6. Red Hat Quay API examples

The remainder of this chapter provides Red Hat Quay API examples for the features in which they are available.

6.1. Managing a user application by using the API

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.

Note

After creation via 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.

Use the following procedure to create a user application token.

Prerequisites

You have created an OAuth 2 access token.

Procedure

Create a user application by entering the POST /api/v1/user/apptoken API 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": "K2YQB1YO0ABYV5OBUYOMF9MCUABN12Y608Q9RHFXBI8K7IE8TYCI4WEEXSVH1AXWKZCKGUVA57PSA8N48PWED9F27PXATFUVUD9QDNCE9GOT9Q8ACYPIN0HL"}}

You can obtain information about your application, including when the application expires, by using the GET /api/v1/user/apptoken command. For example:

$ curl -X GET \
  -H "Authorization: Bearer <access_token>" \
  "http://quay-server.example.com/api/v1/user/apptoken"

{"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": "K2YQB1YO0ABYV5OBUYOMF9MCUABN12Y608Q9RHFXBI8K7IE8TYCI4WEEXSVH1AXWKZCKGUVA57PSA8N48PWED9F27PXATFUVUD9QDNCE9GOT9Q8ACYPIN0HL"}}

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

Red Hat Quay API endpoints are discoverable by using the API.

Use the following procedure to discover available API endpoints.

Prerequisites

You have created an OAuth 2 access token.

Procedure

Enter the following GET /api/v1/discovery command 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

Red Hat Quay API error details are discoverable by using the API.

Use the following procedure to discover error details.

Prerequisites

You have created an OAuth 2 access token.

Procedure

You can 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. Global messages

Global messages can be created, obtained, or deleted by using the Red Hat Quay API. Use the following procedure to create, obtain, or delete a global message.

Prerequisites

You have created an OAuth 2 access token.

Procedure

Create a message by using the POST /api/v1/message endpoint:

$ 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/messages command 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

Logs can be viewed by Organization or repository by using the API. They can also be aggregated (grouped), or listed with more detailed. Logs can also be viewed by user, a specific date range, or by page.

6.5.1. Viewing aggregated logs

Aggregated logs can be viewed by Organization, repository, a specific user, or the current user. You can also pass in optional commands like performer, starttime/endtime, and next_page to filter results.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

Use the GET /api/v1/user/aggregatelogs API 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"

Example 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 performer and starttime/endtime queries 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>"

Aggregated logs can also be viewed by Organization by using the GET /api/v1/organization/{orgname}/aggregatelogs. For example:

$ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  "<quay-server.example.com>/api/v1/organization/{orgname}/aggregatelogs"

Aggregated logs can also be viewed by repository by using the GET /api/v1/repository/{repository}/aggregatelogs command. The following example includes the starttime/endtime fields:

$ 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

Detailed logs can be viewed by Organization, repository, a specific user, or the current user. You can also pass in optional fields like performer, starttime/endtime, and next_page to filter results.

Procedure

Use the GET /api/v1/user/logs API 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 performer and startime/endtime queries 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"

Example 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}/logs endpoint 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}/logs endpoint 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

Detailed logs can be exported to a callback URL or to an email address.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

Use the POST /api/v1/user/exportlogs endpoint 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}/exportlogs endpoint 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}/exportlogs endpoint 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

Red Hat Quay administrators can add and manage labels for tags with the API by using the following procedure.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

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}/labels command 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>/labels

Example 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"}

You can add an additional label to a manifest in a given repository with the POST /api/v1/repository/{repository}/manifest/{manifestref}/labels command. 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>/labels

Example output

{"label": {"id": "346593fd-18c8-49db-854f-4cb1fb76ff9c", "key": "example-key", "value": "example-value", "source_type": "api", "media_type": "text/plain"}}

You can delete a label 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 use one of the commands above to ensure that it was successfully removed.

6.8. Using the API to mirror a repository

Red Hat Quay administrators can mirror external repositories by using the API.

Prerequisites

You have set FEATURE_REPO_MIRROR: true in your config.yaml file.

Procedure

Create a new repository mirror configuration by using the POST /api/v1/repository/{repository}/mirror endpoint:

$ 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>",
        "root_rule": {
            "rule": "<rule>",
            "rule_type": "<rule_type>"
        }
    }'

You can return information about the mirror configuration by using the GET /api/v1/repository/{repository}/mirror endpoint:

$ 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"}

You can use the POST /api/v1/repository/{repository}/mirror/sync-now endpoint to sync the repositories. 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.
Alternatively, you can cancel the sync with the POST /api/v1/repository/{repository}/mirror/sync-cancel endpoint.For example:
```
$ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror/sync-cancel" \
```
This command does not return output in the CLI.

After creating a mirror configuration, you can make changes with the PUT /api/v1/repository/{repository}/mirror command. 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>, 1
        "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>",
        "root_rule": {
            "rule": "<rule>",
            "rule_type": "<rule_type>"
        }
    }'

1: Disables automatic synchronization.

6.9. Establishing quota with the Red Hat Quay API

You can establish quota for an organization or users, and tailor quota policies to suit the needs of your registry.

The following sections show you how to establish quota for an organization, a user, and then how to modify those settings.

6.9.1. Managing organization quota with the Red Hat Quay API

When an organization is first created, it does not have an established quota. You can use the API to check, create, change, or delete quota limitations for an organization.

Prerequisites

You have generated an OAuth access token.

Procedure

To set a quota for an organization, you can use the POST /api/v1/organization/{orgname}/quota endpoint:

$ 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}/quota command 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  | jq

Example 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}

You can 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}

An organization’s quota can be deleted 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 with the Red Hat Quay API

You can set specific quota limits for an organization so that, when exceeded, a warning is returned, or the pushed image is denied altogether.

Procedure

Use the POST /api/v1/organization/{orgname}/quota/{quota_id}/limit command to create a quota policy that rejects images if they exceeded 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", 1
           "threshold_percent": 90 2
         }'

1: One of Reject or Warning.
2: Quota threshold, in percent of quota.

Example output

"Created"

Use the GET /api/v1/organization/{orgname}/quota/{quota_id}/limit 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}

You can 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

You can specify quota and limitations for users so that, when exceeded, a warning is returned, or the pushed image is denied altogether. Quota limits for users must be set on the Red Hat Quay UI. The following APIs can be used to view the quota limits for the user that is logged in.

Procedure

Use the GET /api/v1/user/quota command 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, you can 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}

The limitations can be viewed by using the GET /api/v1/user/quota/{quota_id}/limit endpoint. 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}]

Additional information about the entire policy can be returned 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. Establishing quota with the Red Hat Quay API

Organizations can be created and managed through API endpoints. With the Red Hat Quay API, you can create organizations, view organization information, create proxy caches for an organization, edit users with access to the organization, change organization details, delete organizations, and more.

6.10.1. Creating an organization by using the Red Hat Quay API

Use the following procedure to create a new organization using the Red Hat Quay API.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

Enter the following command to create a new organization 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, organization details can be changed, 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

Use the following procedure to delete an organization using the Red Hat Quay API.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

Enter the following command to delete an organization 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 deleting an organization from the CLI. 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. Retrieving organization member information by using the API

Information about organization members can be retrieved by using the Red Hat Quay API.

Procedure

Use the GET /api/v1/organization/{orgname}/members 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}/collaborators 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.4. Creating an organization application by using the Red Hat Quay API

Organization applications can be created by using the Red Hat Quay UI.

Note

Organization applications can be created by using the UI, however OAuth 2 access tokens must be created on the UI.

Procedure

Use the POST /api/v1/organization/{orgname}/applications endpoint 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}/applications endpoint 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}]}

Applications can also be returned for a specific client 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, organization applications can be updated, for example, if you want to add a redirect URI or a new description, 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, application information can be returned 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"}}}

Organization applications can be deleted 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.5. Configuring a proxy cache for an organization by using the Red Hat Quay API

Proxy caching for an organization can be configured by using the Red Hat Quay API.

Procedure

Use the POST /api/v1/organization/{orgname}/proxycache endpoint 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>"
      }'

Use the POST /api/v1/organization/{orgname}/validateproxycache endpoint 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>"
      }'

Use the GET /api/v1/organization/{orgname}/proxycache endpoint to obtain information about the proxcy 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}/proxycache endpoint to

$ 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

Repository permissions can be managed by using the Red Hat Quay API. For example, you can create, view, and delete user and team permissions.

The following procedures show you how to manage repository permissions by using the Red Hat Quay API.

6.11.1. Managing user permissions by using the Red Hat Quay API

Use the following procedure to manage user permissions by using the Red Hat Quay API.

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}

All user permissions can be returned 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, you can use the GET /api/v1/repository/{repository}/permissions/user/{username}/transitive endpoint 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"}]}

You can change the user’s permissions, such as making the user an admin by using the PUT /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}

User permissions can be deleted 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

Use the following procedure to manage team permissions by using the Red Hat Quay API.

Permissions for a specified team can be returned 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"}

Permissions for all teams can be returned 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"}}}}

Permissions for a specified team can be changed 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"}}

Team permissions can be deleted 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

Auto-prune policies can be created, retrieved, changed, and delete for organizations, repositories, and users by using the Red Hat Quay API.

Procedure

Enter the following command to create a repository using the POST /api/v1/repository endpoint:

$ 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 a repositories with the GET /api/v1/repository endpoint. 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}}]}

Visibility can be changed from public to private with the POST /api/v1/repository/{repository}/changevisibility endpoint:

$ 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}

Repository descriptions can be updated 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 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.12.1. Creating an auto-prune policy for a namespace by using the Red Hat Quay API

You can use Red Hat Quay API endpoints to manage auto-pruning policies for an namespace.

Prerequisites

You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.
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 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 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 tagPattern and tagPatternMatches fields 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> 1
  }' \
  "https://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/"

1: Setting tagPatternMatches to true makes it so that tags that match the given regex pattern will be pruned. In this example, tags that match ^v* are pruned.

Example output

{"uuid": "ebf7448b-93c3-4f14-bf2f-25aa6857c7b0"}

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

You can use Red Hat Quay API endpoints to manage auto-pruning policies for your account.

Note

The use of /user/ in the following commands represents the user that is currently logged into Red Hat Quay.

Prerequisites

You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.
You have created an OAuth access token.
You have logged into Red Hat Quay.

Procedure

Enter the following POST command 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-d75ed8c14859

Example 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-d75ed8c14859

Example output

{"uuid": "8c03f995-ca6f-4928-b98d-d75ed8c14859"}

6.12.3. Creating an auto-prune policy for a repository using the Red Hat Quay API

You can use Red Hat Quay API endpoints to manage auto-pruning policies for an repository.

Prerequisites

You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.
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 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": 2}' http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/

Alternatively, you can 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 tagPattern and tagPatternMatches fields 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> 1
  }' \
  "https://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/"

1: Setting tagPatternMatches to false makes it so that tags that all tags that do not match the given regex pattern are pruned. In this example, all tags but ^test. are pruned.

Example output

{"uuid": "b53d8d3f-2e73-40e7-96ff-736d372cd5ef"}

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-78a9c1bed8c7

Example 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-78a9c1bed8c7

Example output

{"uuid": "ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7"}

6.12.4. Creating an auto-prune policy on a repository for a user with the API

You can use Red Hat Quay API endpoints to manage auto-pruning policies on a repository for user accounts that are not your own, so long as you have admin privileges on the repository.

Prerequisites

You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.
You have created an OAuth access token.
You have logged into Red Hat Quay.
You have admin privileges on the repository that you are creating the policy for.

Procedure

Enter the following POST /api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/ command 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 tagPattern and tagPatternMatches fields 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-becdc6fefce7

Example 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

Repositories can be created, retrieved, changed, and deleted by using the Red Hat Quay API.

6.13.1. Creating and configuring repositories by using the Red Hat Quay API

Repositories can be created, retrieved, changed, and deleted by using the Red Hat Quay API.

Procedure

Enter the following command to create a repository using the POST /api/v1/repository endpoint:

$ 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 a repositories with the GET /api/v1/repository endpoint. 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}}]}

Visibility can be changed from public to private with the POST /api/v1/repository/{repository}/changevisibility endpoint:

$ 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}

Repository descriptions can be updated 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 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

Use the following procedure to add notifications.

Prerequisites

You have created a repository.
You have administrative privileges for the repository.
You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

Enter the following POST /api/v1/repository/{repository}/notification command 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}/test command:

$ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>/test

Example 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>/notification

Example output

{"notifications": []}

6.14. Creating and configuring robot accounts by using the Red Hat Quay API

Robot accounts can be created, retrieved, changed, and deleted for both organizations and users by using the Red Hat Quay API.

6.14.1. Creating a robot account by using the Red Hat Quay API

Use the following procedure to create a robot account using the Red Hat Quay API.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

Enter the following command to create a new robot account for an organization 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

Robot account information, such as permissions, can be obtained for both organizations and users by using the Red Hat Quay API.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

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": "BILZ6YTVAZAKOGMD9270OKN3SOD9KPB7OLKEJQOJE38NBBRUJTIH7T5859DJL31Q", "unstructured_metadata": {}}

Use the GET /api/v1/organization/{orgname}/robots/{robot_shortname}/permissions endpoint 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": "QBFYWIWZOS1I0P0R9N1JRNP1UZAOPUIR3EB4ASPZKK9IA1SFC12LTEF7OJHB05Z8", "unstructured_metadata": {}}

Use the GET /api/v1/user/robots/{robot_shortname}/permissions API 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

Use the following procedure to delete a robot account using the Red Hat Quay API.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

Enter the following command to delete a robot account for an organization 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}/robots command 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

You can use search API endpoints to perform searches against all registry context.

Procedure

Use the GET /api/v1/find/repositories endpoint 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/all endpoint 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. View Clair security scans by using the API

You can view Clair security scans by using the API.

Procedure

Use the GET /api/v1/repository/{repository}/manifest/{manifestref}/security endpoint 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

Through the Red Hat Quay UI, superusers have the ability to create, list, change, and delete aspects of the registry, such as users, service keys, a user’s quota, and more.

6.17.1. Creating a user account by using the Red Hat Quay API

Use the following procedure to create a new user for your Red Hat Quay repository by using the API.

Prerequisites

You are logged into your Red Hat Quay deployment as a superuser.
You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

Enter the following command to create a new user 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.com and login with the username and password generated from the API call. In this scenario, the username is newuser and the password is 123456789. Alternatively, you can log in to the registry with the CLI. For example:
```
$ podman login <quay-server.example.com>
```
Example output
```
username: newuser
password: 123456789
```

Optional. 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/"

Note

The GET /api/v1/superuser/users/ endpoint only returns users and superusers if AUTHENTICATION_TYPE: Database is set in your config.yaml file. It does not work for LDAP authentication 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

Use the following procedure to delete a user from Red Hat Quay using the API.

Important

After deleting the user, any repositories that this user had in his private account become unavailable.

Prerequisites

You are logged into your Red Hat Quay deployment as a superuser.
You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

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.
Note
The GET /api/v1/superuser/users/ endpoint only returns users and superusers if AUTHENTICATION_TYPE: Database is set in your config.yaml file. It does not work for LDAP authentication 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

Superusers have the ability to list, change, and delete organizations by using the Red Hat Quay API.

Procedure

Use the GET /api/v1/superuser/organizations endpoint 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 and 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

Red Hat Quay superusers can list usage logs for the current system.

Procedure

Use the GET /api/v1/superuser/logs endpoint 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/ end point 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/ end point 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

Quota can be managed with the Red Hat Quay API with superuser admin privileges. These endpoints allow superusers to manage quota policies for all organizations within the registry.

Procedure

Use the POST /api/v1/superuser/organization/{namespace}/quota API 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}/quota API 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

$ 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

As a superuser, you can manage user quota for specified organizations.

Procedure

Use the POST /api/v1/superuser/users/{namespace}/quota endpoint 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}/quota endpoint 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

As a superuser, you can retrieve information about builds with the Red Hat Quay API.

Procedure

Use the GET /api/v1/superuser/{build_uuid}/build endpoint to return information about a build:

$ curl -X GET "https://quay-server.example.com/api/v1/superuser/<build_uuid>/build" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Use the GET /api/v1/superuser/{build_uuid}/status API endpoint to return the status for the builds specified by the build uuids:

$ curl -X GET "https://quay-server.example.com/api/v1/superuser/<build_uuid>/status" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Use the GET /api/v1/superuser/{build_uuid}/logs API endpoint to return the build logs for the build specified by the build uuid:

$ 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

Superusers have the ability to create, list, change, and delete service keys by using the Red Hat Quay API.

Procedure

Use the POST /api/v1/superuser/keys endpoint to create a service key:

$ 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":""}

Use the POST /api/v1/superuser/approvedkeys/{kid} endpoint to approved a service key:

$ 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.

Use the GET /api/v1/superuser/keys endpoint to list service keys:

$ 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"}]}

Use the GET /api/v1/superuser/keys/{kid} endpoint to retrieve information about a service account by its kid:

$ 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"}

Use the PUT /api/v1/superuser/keys/{kid} endpoint to update your service key, such as the metadata:

$ 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"}

Use the DELETE /api/v1/superuser/keys/{kid} endpoint to delete a service key:
```
$ 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

Tags can be changed, restored, deleted, or listed by using the Red Hat Quay API.

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}/restore endpoint 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

Team can be managing by using the Red Hat Quay API.

6.19.1. Managing team members and repository permissions by using the API

Use the following procedures to add a member to a team (by direct invite or by email), or to remove a member from a team.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

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 an output in the CLI. To ensure that a member has been deleted, you can enter the GET /api/v1/organization/{orgname}/team/{teamname}/members command 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

Use the following procedure to view and set the role a team within an organization using the API.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

Enter the following GET /api/v1/organization/{orgname}/team/{teamname}/permissions command 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

Use the following procedure to delete a team within an organization by using the API.

Prerequisites

You have Created an OAuth access token.
You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

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

Builds can be managed by using the Red Hat Quay API.

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}/activate endpoint 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}/start endpoint 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}/builds endpoint 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

Some user options, like starring a repository, or getting information about your account, are available with the Red Hat Quay API.

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/starred endpoint 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/starred endpoint 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.

Legal Notice

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Red Hat Quay API guide