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

Project 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 Project Quay 2.0 differs from Project 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 Project 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 Project Quay’s robot tokens

  • Generating an OAuth 2 access token from the API Access Tokens page

  • Revoking and migrating OAuth 2 access tokens

  • Best practices for token management

  • OAuth 2 access token capabilities

  • Using the Project Quay API

  • Programmatic OAuth token provisioning

  • Project Quay API configuration examples

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

Additional resources

Introduction to Project Quay OAuth 2.0 tokens

OAuth 2.0 tokens provide secure, standards-based access to the Project Quay API. You can use OAuth 2 access tokens, robot account tokens, and OCI referrers access tokens to authenticate API operations.

Compared to more traditional API tokens, Project Quay OAuth 2 tokens offer the following enhancements:

  • Standards-based security that adheres to the OAuth 2.0 protocol.

  • Revocable access by deleting the application in which the OAuth 2 token exists.

  • Fine-grained access control so that Project Quay administrators can assign specific permissions to tokens.

  • Delegated access so that third-party applications and services can act on behalf of a user.

  • Compatibility with other services, platforms, and integrations.

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

You can manage organization OAuth 2 access tokens from the API Access Tokens page of an OAuth application. You can create named tokens with optional expiration, review metadata such as scopes and last-used time, and revoke individual tokens without deleting the parent application.

Additional resources

OAuth 2 access tokens

OAuth 2 access tokens authenticate users to the Project Quay API for applications that require user identity verification. You create a token for an organization OAuth application and select scopes that authorize API actions.

Note

Although OAuth 2 tokens authorize actions on API endpoints based on the scopes that you define for the token, Project Quay role-based access control (RBAC) still governs access to the resources. You can create actions on a resource, for example a repository, when you have the proper role (Admin or Creator) for that namespace. This is true even if the API token was granted the repo:admin scope.

You can create OAuth 2 access tokens by using the Project Quay UI or by using the organization application token API.

When you create an OAuth 2 token, you can select the following options:

  • Name. A user-defined identifier for the token.

  • Expiration. A lifetime for the token. Use short expirations for scripts and CI systems when practical. Use no expiration only for controlled bootstrap cases.

  • Scopes, which can include the following permissions:

    • Administer Organization. Administration of organizations, including creating robots, creating teams, adjusting team membership, and changing billing settings.

    • Administer Repositories. Administrator access to all repositories to which the granting user has access.

    • Create Repositories. Creation of repositories in namespaces where the granting user can create repositories.

    • View all visible repositories. Viewing and pulling all repositories visible to the granting user.

    • Read/Write to any accessible repositories. Viewing, pushing, and pulling to repositories where the granting user has write access.

    • Super User Access. Administration of the installation, including managing users and organizations from the superuser panel.

    • Administer User. Administration of your account, including creating robots and granting them repository permissions.

    • Read User Information. Reading user information such as username and email address.

The API Access Tokens page can show additional columns such as Created By, Expires, and Last Used so that you can audit tokens without deleting the parent application.

Important

The token secret is shown only when the token is created. Store it securely. Do not share token secrets through insecure channels.

OAuth 2 access tokens are passed as a Bearer token in the Authorization header of an API call. The API is available from the /api/v1 endpoint of your Project Quay host. For example, https://<quay-server.example.com>/api/v1. You can connect to endpoints through your browser to GET, POST, DELETE, and PUT Project Quay settings by enabling the Swagger UI. Applications that make API calls and use OAuth tokens can access the API, which sends and receives data as JSON.

Organization application OAuth API tokens created through the UI support various expiration values, from 7 days to 10 years. Tokens created by using the organization application token API support custom expiration values in seconds. You can revoke tokens individually by using the API or by deleting the application in which they were created. Deleting an application revokes all tokens created within that application.

Token distributors should be mindful of the permissions that they grant 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 Project Quay UI. If an access token is lost or forgotten, a new token must be created; a token cannot be recovered.

In practice, Project Quay administrators can create a new OAuth application on the OAuth Applications page of their organization each time they want to create a new OAuth token for a user. This ensures that a single application is not responsible for all OAuth tokens. As a result, if a user’s token is compromised, the administrator can delete the application of the compromised token without disrupting other users whose tokens might be part of the same application.

Older tokens that you created with the previous Generate Token workflow continue to work. In the API Access Tokens list, legacy tokens might appear with a name such as Legacy Token. You can leave them in place, or replace them with named tokens that have explicit expiration policies and then revoke the legacy token.

Note

Deleting an OAuth application still deletes all tokens that belong to that application. Prefer revoking an individual token from the API Access Tokens page when you only need to invalidate one credential.
Additional resources

Creating an OAuth 2 access token

To create an OAuth 2 access token for Project Quay API calls, you can generate a named token from an organization OAuth application in the UI.

Prerequisites

  • You have logged in to Project Quay as an administrator.

  • You have created an organization.

Procedure

  1. On the Project Quay UI, select your organization.

  2. In the navigation pane, click OAuth Applications.

  3. Create an application if you do not already have one:

    1. Click Create OAuth Application.

    2. Enter an application name and any required application details, such as homepage URL, description, avatar e-mail, and redirect/callback URL.

    3. Click Create application.

  4. Click the name of your OAuth application.

  5. Click API Access Tokens.

  6. Click Generate New Token.

  7. Configure the token:

    1. Enter a Token name.

    2. Set an expiration period, such as 10 years.

    3. Optional: Click Assign another user to assign this OAuth token to another user. When prompted, select the desired user.

    4. Select the permissions, or scopes, for the token. For example:

      1. Administer Organization. This application can administer your organizations, including creating robots, creating teams, adjusting team membership, and changing billing settings. Grant this permission only when you have absolute trust in the requesting application.

      2. Administer Repositories. This application has administrator access to all repositories to which the granting user has access.

      3. Create Repositories. This application can create repositories in all namespaces where the granting user can create repositories.

      4. View all visible repositories. This application can view and pull all repositories visible to the granting user.

      5. Read/Write to any accessible repositories. This application can view, push, and pull to all repositories to which the granting user has write access.

      6. Super User Access. This application can administer your installation, including managing users, managing organizations, and other features found in the superuser panel. Grant this permission only when you have absolute trust in the requesting application.

      7. Administer User. This application can administer your account, including creating robots and granting them permissions to your repositories. Grant this permission only when you have absolute trust in the requesting application.

      8. Read User Information. This application can read user information such as username and email address.

  8. Click Generate token.

  9. Review the requested permissions, then click Authorize Application. Confirm the authorization when prompted.

    Important

    Assign only the scopes that the token holder needs. Treat Administer Organization, Super User Access, and Administer User as high-trust permissions.

  10. Copy and store the access token secret.

    Important

    This is the only opportunity to copy the token secret. Project Quay does not show the full secret again after you leave the page.
Verification

  1. Confirm that the new token appears on the API Access Tokens page for the application. The list can include the token name, creator, scopes, expiration, and last-used information when those columns are available.

  2. Optional. Call an API endpoint with the token to confirm that it works. For example:

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

Reassigning an OAuth access token

To keep audit logs accurate when another user needs an OAuth API token, you can reassign token creation to that user from an organization OAuth application.

Organization administrators can assign OAuth API tokens to be created by other users with specific permissions. Audit logs then reflect the user who uses the token, even when that user does not have organization administrative permissions to create an OAuth API token.

Note

This procedure works only on the current Project Quay UI. The Project Quay v2 UI does not currently support this procedure.
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.
Procedure

  1. Optional. If not already, update your Project Quay config.yaml file to include the FEATURE_ASSIGN_OAUTH_TOKEN: true field:

    # ...
FEATURE_ASSIGN_OAUTH_TOKEN: true
# ...

  2. Optional. Restart your Project Quay registry.

  3. Log in to your Project Quay registry as an organization administrator.

  4. Click the name of the organization in which you created the OAuth token.

  5. In the navigation pane, click OAuth Applications.

  6. Click the proper application name.

  7. In the navigation pane, click API Access Tokens.

  8. Click Generate New Token.

  9. Click Assign another user and enter the name of the user who takes over the OAuth token.

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

    The team role within an organization defines permission control 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 by using the config.yaml file and the box must be checked here.

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

  12. Click Assign token in the popup box. You are redirected to a new page that displays the following message:

    Token assigned successfully
Verification

  1. After reassigning an OAuth token, the assigned user must accept the token to receive the bearer token, which is required to use API endpoints. Ask the assigned user to log in to the Project Quay registry.

  2. After the assigned user has logged in, ask them to click their username under Users and Organizations.

  3. In the navigation pane, ask them to click External Logins And Applications.

  4. Under Authorized Applications, ask them to confirm the application by clicking Authorize Application. They are directed to a new page where they must reconfirm by clicking Authorize Application.

  5. They are redirected to a new page that reveals their bearer token. Ask them to save this bearer token, because it cannot be viewed again.

Additional resources

Revoking an OAuth 2 access token

To invalidate a compromised or unused OAuth 2 access token, you can revoke the token from the organization OAuth application in the Project Quay UI.

Because OAuth 2 access tokens are created through the OAuth application, they cannot be rotated or renewed. If a token is compromised, revoke it through the Project Quay UI.

Prerequisites

  • You have created an OAuth 2 access token.

  • You have permission to manage the OAuth application that owns the token.

Procedure

  1. On the Project Quay UI, click the name of the organization that hosts the application.

  2. In the navigation pane, click OAuth Applications.

  3. Click the application name that holds the OAuth 2 token that you want to revoke.

  4. Click API Access Tokens.

  5. Click the menu kebab of the appropriate token and then click Revoke. Confirm that you want to revoke the token by clicking Revoke token.

Verification

  1. Confirm that the token no longer appears as an active token on the API Access Tokens page.

Rotating a legacy OAuth 2 access token

To replace a legacy long-lived OAuth 2 access token, you can create a named token with an explicit expiration policy and then revoke the legacy token.

Existing legacy tokens continue to work for at least 10 years until you revoke them.

Prerequisites

  • You have an organization OAuth application that already has a legacy token.

  • You can update any CI system, script, or client that currently uses the legacy token.

Procedure

  1. On the Project Quay UI, click Organization → OAuth Applications.

  2. Click the application name.

  3. Click API Access Tokens.

  4. Identify the legacy token to replace. Legacy tokens do not have a user-defined name, do not show a creation date, and have an expiration date of 10 years from the date of creation.

  5. Click Generate New Token.

  6. Configure a replacement token:

    1. Enter a Token name.

    2. Set an expiration appropriate for the workload, for example 7 days or 10 years.

    3. Select the scopes required by the client.

  7. Click Generate Token, then click Authorize Application and confirm the authorization.

  8. Copy the new token secret and store it securely.

  9. Update the CI system, script, or client configuration to use the new token.

  10. Verify that the client works with the new token.

  11. Return to the OAuth Applications page and revoke the legacy token:

    1. Click the application name that owns the legacy token.

    2. Click the menu kebab icon for the legacy token.

    3. Click Revoke. Confirm that you want to revoke the token by clicking Revoke token.

Robot account tokens

Robot account tokens are persistent password-type credentials for Docker v2 registry access in Project Quay. You can use them for automation and continuous integration without interactive user authentication.

Robot account tokens are password-type credentials used to access a Project Quay registry by using normal Docker v2 endpoints. The UI labels these credentials as tokens because the password itself is encrypted.

By default, Project Quay 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 not user-specific; they are connected to the user and organization namespace where they are created. For example, a robot named project_tools+<robot_name> belongs to 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 Project Quay without manual renewal. Despite this, you can regenerate robot account tokens by using the UI or by using the proper API endpoint from the CLI. To enhance the security of your Project Quay deployment, administrators should regularly refresh robot account tokens. With the keyless authentication with robot accounts feature, you can exchange robot account tokens for external OIDC tokens so that they last only one hour, which enhances the security of your registry.

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

Additional resources

Regenerating a robot account token by using the Project Quay UI

To replace a robot account credential from the Project Quay UI, you can regenerate the robot account token for an organization robot account.

Prerequisites

  • You have logged into Project Quay.

Procedure

  1. Click the name of an organization.

  2. In the navigation pane, click Robot accounts.

  3. Click the name of your robot account, for example, testorg3+test.

  4. Click Regenerate token in the popup box.

Regenerating a robot account token by using the Project Quay API

To replace a compromised or outdated robot account credential, you can regenerate a robot account token by using the Project Quay API for organization or user robots.

Prerequisites

  • You have created an OAuth access token.

Procedure

  • Enter the following command to regenerate a robot account token for an organization by 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 by using 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>"}
Additional resources

OCI referrers OAuth access token

An OCI referrers OAuth access token lists OCI referrers of a manifest under a repository in Project Quay. You obtain the token through basic HTTP authentication against the v2/auth endpoint.

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

You obtain these tokens by using 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 and 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 resources

Creating an OCI referrers OAuth access token

To list OCI referrers of a manifest under a repository, you can create an OCI referrers OAuth access token by using basic authentication against the Project Quay v2/auth endpoint.

Procedure

  1. Update your config.yaml file to include the FEATURE_REFERRERS_API: true field. For example:

    # ...
FEATURE_REFERRERS_API: true
# ...

  2. Enter the following command to Base64 encode your credentials:

    $ echo -n '<username>:<password>' | base64
    Example output
    abcdeWFkbWluOjE5ODlraWROZXQxIQ==

  3. Enter the following command to use the Base64-encoded string and modify the URL endpoint to your Project 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>"
}

Enabling and using the Project Quay API

The Project Quay API provides endpoints to automate registry tasks such as repository, user, and image management. You can integrate these endpoints into your existing workflows.

Using the Project Quay API

To invoke Project Quay API endpoints from the CLI, you can pass an OAuth 2 access token in a curl request. You can use GET, PUT, POST, or DELETE methods against the documented endpoints.

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 Project Quay API command looks similar to the following example:

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

+ where:

<your_access_token>

Specifies the OAuth 2 access token that was generated through the Project Quay UI.

https://<quay-server.example.com>/api/v1/<example>/<endpoint>/

Specifies your Project Quay deployment and the desired API endpoint.

All Project 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*
Create a new app specific token for user.

*POST /api/v1/user/apptoken*

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

 Request body schema (application/json)

*Path parameters*

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

*Responses*

|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;
|===

+ where:

createAppToken

Specifies the name of the API endpoint.

Create a new app specific token for user.

Specifies a brief description of the API endpoint.

POST /api/v1/user/apptoken

Specifies the API endpoint used for invocation.

Authorizations

Specifies the authorizations required to use the API endpoint.

Path parameters

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

Responses

Specifies the API responses for this endpoint.

Using a Project Quay API endpoint

To use an API endpoint, you pass in your access token and then include the appropriate fields depending on your needs.

Prerequisites

  • You have access to the Project Quay API, which entails having already 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"

    where:

    <access_token>

    Specifies the OAuth access token.

    "MyAppToken"

    Specifies the name of your application token.

    http://quay-server.example.com/api/v1/user/apptoken

    Specifies your Project 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": "string"}}
Verification

  • On the Project 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:

    Application token
Additional resources

Enabling browser-based API calls in Project Quay

To use Project Quay API access from a browser extension or Swagger UI, you can disable BROWSER_API_CALLS_XHR_ONLY in your config.yaml file.

By default, Project Quay accepts curl requests from the command line. However, if you want to enable API access from a browser extension such as Postman, or a browser interface such as Swagger, you must disable BROWSER_API_CALLS_XHR_ONLY in your config.yaml file.

Procedure

  1. In your Project Quay config.yaml file, set BROWSER_API_CALLS_XHR_ONLY to false. For example:

    # ...
BROWSER_API_CALLS_XHR_ONLY: false
# ...

  2. Restart your Project Quay deployment.

Accessing Project Quay Swagger UI

To explore and test Project Quay API endpoints interactively, you can run the Swagger UI container against your registry API discovery endpoint.

Project Quay administrators and users can interact 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 Project 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 Project Quay from the specified URL. Project Quay administrators and users can explore the available endpoints and their structure.

Prerequisites

  • You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

  1. Enter the following command to deploy the Swagger UI container, pointing the URL to your Project Quay 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
---

  2. Navigate to the localhost URL. In this example, the URL is http://localhost:8080/.

  3. 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 configured 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>'.

Automating Project Quay processes by using the API

To automate repetitive Project Quay tasks such as repository management or image pruning, you can call the API from scripts and schedule them with cron.

With the API, Project 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 Project Quay API, which entails having already created an OAuth 2 access token.

  • You have installed the Python requests library.

  • You have enabled cron jobs on your machine.

  • You have created several organization applications, including one that you do not want to delete.

Procedure

  1. Create a Python script that executes an API command. The following example deletes organization applications by using the DELETE /api/v1/organization/{orgname}/applications/{client_id} API endpoint.

    Create the following example.py file:

    import requests

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

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>":  # 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()

    where:

    import requests

    Specifies that the requests library is included in your Python code.

    API_BASE_URL

    Specifies the URL of your registry appended with /api/v1.

    ACCESS_TOKEN

    Specifies your OAuth 2 access token.

    ORG_NAME

    Specifies the organization that holds the application.

    "<admin_token_app>"

    Specifies the name of the application token to remain.

  2. Save the script as prune_applications.py.

  3. 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
Additional resources

Programmatic OAuth token provisioning

To create and manage organization application tokens without the UI, you can use programmatic OAuth token provisioning through the REST API. You can also enable a Tech Preview bootstrap token for zero-touch automation.

Organization OAuth applications previously required administrators to create API tokens in the Project Quay UI. With programmatic token provisioning, automation tools can manage the token life cycle.

When FEATURE_PROGRAMMATIC_BOOTSTRAP is enabled, Project Quay also creates a high-privilege bootstrap OAuth token on startup and writes it to a local file or Kubernetes Secret. Use the bootstrap token to create organizations, applications, and narrower-scoped tokens without interactive UI access.

Important

Programmatic bootstrap token provisioning is a Tech Preview feature in Project Quay 3.18. Tech Preview features are not supported with Red Hat production service-level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using Tech Preview features in production environments. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
Additional resources

Project Quay API examples

Project Quay API examples show how to call common endpoints for applications, discovery, errors, messages, and logs. You can adapt these examples for your registry workflows.

Managing a user application by using the API

To create, list, or delete a user application token without sharing your password, you can use the Project Quay API. User application tokens work like encrypted username and password credentials for Docker, Podman, or other clients.

Project 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 Project Quay.

Note

After creation by using the CLI, the user application token is listed under User Settings of the Project Quay UI. Note that this differs from an application token that is created under user settings, and should be considered a different application entirely.
Prerequisites

  • You have created an OAuth 2 access token.

Procedure

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

  • 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"
    Example output
    {"tokens": [{"uuid": "6b5aa827-cee5-4fbe-a434-4b7b8a245ca7", "title": "MyAppToken", "last_accessed": null, "created": "Wed, 08 Jan 2025 19:32:48 -0000", "expiration": null}], "only_expiring": null}

  • You can obtain information about a specific user application by entering the GET /api/v1/user/apptoken/{token_uuid} command:

    $ curl -X GET \
  -H "Authorization: Bearer <access_token>" \
  "http://quay-server.example.com/api/v1/user/apptoken/<token_uuid>"
    Example output
    {"token": {"uuid": "6b5aa827-cee5-4fbe-a434-4b7b8a245ca7", "title": "MyAppToken", "last_accessed": null, "created": "Wed, 08 Jan 2025 19:32:48 -0000", "expiration": null, "token_code": "string"}}

  • You can delete or revoke a user application token by using the DELETE /api/v1/user/apptoken/{token_uuid} endpoint:

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

    This command does not return output in the CLI. You can return a list of tokens by entering one of the aforementioned commands.

Additional resources

Discovering Project Quay API endpoints

To list available Project Quay API endpoints in Swagger format, you can call the discovery endpoint with an OAuth 2 access token.

Prerequisites

  • You have created an OAuth 2 access token.

Procedure

  • Enter the following GET /api/v1/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": ""}]}
---
Additional resources

Obtaining Project Quay API error details

To retrieve details for a Project Quay API error type, you can call the error endpoint with an OAuth 2 access token and an error code.

Prerequisites

  • You have created an OAuth 2 access token.

Procedure

  • Obtain error details of the API by entering the GET /api/v1/error/{error_type} endpoint. Note that you must include one of the following error codes:

    HTTP Code Description

    200

    Successful invocation

    400

    Bad Request

    401

    Session required

    403

    Unauthorized access

    404

    Not found

    		 
    $ curl -X GET "https://<quay-server.example.com>/api/v1/error/<error_type>" \
    -H "Authorization: Bearer <access_token>"
    Example output
    curl: (7) Failed to connect to quay-server.example.com port 443 after 0 ms: Couldn't connect to server
Additional resources

Managing global messages by using the API

To create, list, or delete global messages in Project Quay, you can use the messages API endpoints with an OAuth 2 access token.

Prerequisites

  • You have created an OAuth 2 access token.

Procedure

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

  2. 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"}]}

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

Additional resources

Viewing usage logs by using the API

To review registry activity, you can view usage logs by organization or repository through the Project Quay API. You can aggregate logs, list detailed entries, filter by user or date range, and page through results.

Additional resources

Viewing aggregated logs

To review grouped activity for a user, organization, or repository in Project Quay, you can retrieve aggregated logs through the API. You can filter results by performer and date range.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. 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"

    The following example shows aggregated log output:

    {"aggregated": [{"kind": "create_tag", "count": 1, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}, {"kind": "manifest_label_add", "count": 1, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}, {"kind": "push_repo", "count": 2, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}, {"kind": "revert_tag", "count": 1, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}]}

    You can also pass in the 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>"

  2. View aggregated logs by organization by using the GET /api/v1/organization/{orgname}/aggregatelogs endpoint. For example:

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

  3. View aggregated logs by repository by using the GET /api/v1/repository/{repository}/aggregatelogs endpoint. 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""
Additional resources

Viewing detailed logs

To inspect individual registry events for a user, organization, or repository in Project Quay, you can retrieve detailed logs through the API. You can filter results by performer and date range.

Procedure

  1. 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 starttime/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"

    The following example shows detailed log output:

    ---
{"start_time": "Mon, 01 Jan 2024 00:00:00 -0000", "end_time": "Wed, 19 Jun 2024 00:00:00 -0000", "logs": [{"kind": "revert_tag", "metadata": {"username": "quayuser", "repo": "busybox", "tag": "test-two", "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d"}, "ip": "192.168.1.131", "datetime": "Tue, 18 Jun 2024 18:59:13 -0000", "performer": {"kind": "user", "name": "quayuser", "is_robot": false, "avatar": {"name": "quayuser", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}}}, {"kind": "push_repo", "metadata": {"repo": "busybox", "namespace": "quayuser", "user-agent": "containers/5.30.1 (github.com/containers/image)", "tag": "test-two", "username": "quayuser", }
---

  2. 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"

  3. 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"
Additional resources

Exporting logs by using the API

To export detailed Project Quay logs for a user, organization, or repository, you can call the export logs API endpoints and deliver the results to a callback URL or email address.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. 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"}

  2. 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"

  3. 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"
Additional resources

Adding and managing labels by using the API

To add, list, retrieve, or delete labels on image manifests in Project Quay, you can use the repository manifest labels API endpoints with an OAuth 2 access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

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

  2. 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"}]}

  3. 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"}

  4. 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"}}

  5. Delete a label by using the DELETE /api/v1/repository/{repository}/manifest/{manifestref}/labels/{labelid} command:

    $ curl -X DELETE \
  -H "Authorization: Bearer <bearer_token>" \
  https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels/<labelid>

    This command does not return output in the CLI. You can list labels again to confirm that the label was removed.

Additional resources

Using the API to mirror a repository

To mirror an external repository into Project Quay, you can create and manage a repository mirror configuration through the API. You can also sync, cancel, or update the configuration.

Prerequisites

  • You have set FEATURE_REPO_MIRROR: 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>",
        "skopeo_timeout_interval": 600,
        "root_rule": {
            "rule": "<rule>",
            "rule_type": "<rule_type>"
        }
    }'

  • Return information about the mirror configuration by using the GET /api/v1/repository/{repository}/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"}

  • Sync the repositories by using the POST /api/v1/repository/{repository}/mirror/sync-now endpoint. For example:

    $ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror/sync-now" \
     -H "Authorization: Bearer <access_token>"

    This command does not return output in the CLI.

  • Cancel the sync with the POST /api/v1/repository/{repository}/mirror/sync-cancel endpoint. For example:

    $ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror/sync-cancel" \
     -H "Authorization: Bearer <access_token>"

    This command does not return output in the CLI.

  • After creating a mirror configuration, make changes with the PUT /api/v1/repository/{repository}/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>,
        "external_reference": "<external_reference>",
        "external_registry_username": "<external_registry_username>",
        "external_registry_password": "<external_registry_password>",
        "sync_start_date": "<sync_start_date>",
        "sync_interval": <sync_interval>,
        "robot_username": "<robot_username>",
        "skopeo_timeout_interval": 600,
        "root_rule": {
            "rule": "<rule>",
            "rule_type": "<rule_type>"
        }
    }'

    Where:

    "is_enabled": <false>

    Disables automatic synchronization.

Additional resources

Establishing quota with the Project Quay API

Quota policies in Project Quay set storage limits for organizations and users so that you can control registry capacity. You can create, view, update, and delete quota settings through the API.

Managing organization quota with the Project Quay API

To manage storage quota for an organization in Project Quay, you can use the organization quota API endpoints. You can check, create, change, or delete quota limitations.

When an organization is first created, it does not have an established quota.

Prerequisites

  • You have generated an OAuth access token.

Procedure

  1. To set a quota for an organization, 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"

  2. 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}

  3. 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}

  4. Delete an organization’s quota with the DELETE /api/v1/organization/{orgname}/quota/{quota_id} command. For example:

    $ curl -X DELETE "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota/<quota_id>" \
     -H "Authorization: Bearer <access_token>"

    This command does not return output.

Additional resources

Setting quota limits for an organization by using the Project Quay API

To return a warning or deny image pushes when an organization exceeds its quota in Project Quay, you can create, list, update, and delete organization quota limits through the API.

Procedure

  1. Use the POST /api/v1/organization/{orgname}/quota/{quota_id}/limit command to create a quota policy that rejects images if they exceed the allotted quota. For example:

    $ curl -X POST "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota/<quota_id>/limit" \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
           "limit_bytes": 21474836480,
           "type": "Reject",
           "threshold_percent": 90
         }'

    where:

    type

    Specifies one of Reject or Warning.

    threshold_percent

    Specifies the quota threshold, in percent of quota.

    Example output
    "Created"

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

  3. 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}

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

Additional resources

Obtaining quota limits for the user with the Project Quay API

To view storage quota and limit policies for the logged-in user in Project Quay, you can call the user quota API endpoints.

Quota limits for users must be set on the Project Quay UI. The following APIs return the quota limits for the user that is logged in.

Procedure

  1. 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}]

  2. After you have received the quota ID, pass it in with the GET /api/v1/user/quota/{quota_id} endpoint to return information about the limitation:

    $ curl -X GET "https://<quay-server.example.com>/api/v1/user/quota/{quota_id}" \
  -H "Authorization: Bearer <access_token>"
    Example output
    {"id": 4, "limit_bytes": 2199023255552, "limit": "2.0 TiB", "default_config": false, "limits": [], "default_config_exists": false}

  3. View the limitations 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}]

  4. Return additional information about the entire policy by using the GET /api/v1/user/quota/{quota_id}/limit/{limit_id} endpoint:

    $ curl -X GET "https://<quay-server.example.com>/api/v1/user/quota/{quota_id}/limit/{limit_id}" \
  -H "Authorization: Bearer <access_token>"
    Example output
    {"id": 4, "limit_bytes": 2199023255552, "limit": "2.0 TiB", "default_config": false, "limits": [{"id": 3, "type": "Reject", "limit_percent": 100}], "default_config_exists": false}
Additional resources

Managing organizations by using the API

To create and manage organizations in Project Quay, you can use organization API endpoints. You can view organization details, manage members, configure proxy caches, and delete organizations.

Creating an organization by using the Project Quay API

To create an organization in Project Quay, you can call the organization API endpoint with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. Enter the following command to create a new organization by using the POST /api/v1/organization/ endpoint:

    $ curl -X POST   -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json"   -d '{
    "name": "<new_organization_name>"
  }'   "https://<quay-server.example.com>/api/v1/organization/"
    Example output
    "Created"

  2. After creation, you can change organization details, such as adding an email address, with the PUT /api/v1/organization/{orgname} command. For example:

    $ curl -X PUT "https://<quay-server.example.com>/api/v1/organization/<orgname>" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "<org_email>",
        "invoice_email": <true/false>,
        "invoice_email_address": "<billing_email>"
      }'
    Example output
    {"name": "test", "email": "new-contact@test-org.com", "avatar": {"name": "test", "hash": "a15d479002b20f211568fd4419e76686d2b88a4980a5b4c4bc10420776c5f6fe", "color": "#aec7e8", "kind": "user"}, "is_admin": true, "is_member": true, "teams": {"owners": {"name": "owners", "description": "", "role": "admin", "avatar": {"name": "owners", "hash": "6f0e3a8c0eb46e8834b43b03374ece43a030621d92a7437beb48f871e90f8d90", "color": "#c7c7c7", "kind": "team"}, "can_view": true, "repo_count": 0, "member_count": 1, "is_synced": false}}, "ordered_teams": ["owners"], "invoice_email": true, "invoice_email_address": "billing@test-org.com", "tag_expiration_s": 1209600, "is_free_account": true, "quotas": [{"id": 2, "limit_bytes": 10737418240, "limits": [{"id": 1, "type": "Reject", "limit_percent": 90}]}], "quota_report": {"quota_bytes": 0, "configured_quota": 10737418240, "running_backfill": "complete", "backfill_status": "complete"}}
Additional resources

Deleting an organization by using the Project Quay API

To delete an organization in Project Quay, you can call the organization API endpoint with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. Enter the following command to delete an organization by using the DELETE /api/v1/organization/{orgname} endpoint:

    $ curl -X DELETE \
  -H "Authorization: Bearer <bearer_token>" \
  "https://<quay-server.example.com>/api/v1/organization/<organization_name>"

  2. The CLI does not return information when you delete an organization. To confirm deletion, you can check the Project 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}
Additional resources

Managing organization contact email with the API

Use the organization contact email setting to configure where automated system alerts are sent for an organization. The contact_email field allows multiple organizations to share the same notification address without requiring separate user accounts for each team.

Note

In the Project Quay web UI, the contact_email field is labeled as Organization creation: "Email (Optional)" and Organization Settings page: "Email".

The organization contact_email field has the following properties:

  • Receives namespace-level notifications (such as quota warnings and quota errors), billing and payment alerts (invoices, payment failures), and organization account recovery emails.

  • Can be shared across multiple organizations (useful for team distribution lists).

  • An optional setting; if left empty, notifications default to organization owners.

Note

When FEATURE_ORG_SHARED_EMAIL: false, Project Quay enforces email uniqueness by default so that the same address cannot be used by more than one user or organization entity. This is a backend restriction and not a UI-only rule. It applies during organization creation only, not when you later update an organization contact email. At creation time, the organization contact email cannot match any existing user account email in the system.

When you set FEATURE_ORG_SHARED_EMAIL: true in your config.yaml file, the same email address can be shared across multiple organizations and with at most one user account.
Note

For POST and PUT requests, the API accepts both email and contact_email fields. When both are provided, contact_email takes precedence. The email field is retained for backward compatibility, but new integrations should use contact_email.
Prerequisites
Procedure

  • To retrieve the current email configured for an organization, use the following GET /api/v1/organization/{orgname} endpoint:

    $ curl -X GET \
-H "Authorization: Bearer <bearer_token>" \
"https://<quay-server.example.com>/api/v1/organization/engineering"
    Example response
    {
  "name": "engineering",
  "email": "team-notifications@example.com",
  "is_admin": true
}

    When an email address is not configured, the API response returns "email": "".

  • To set the contact email when creating an organization, pass the contact_email field by using the POST /api/v1/organization/ endpoint:

    $ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
-d '{"name": "engineering", "contact_email": "team-alerts@example.com"}' \
"https://<quay-server.example.com>/api/v1/organization/"

  • To update the contact email for an existing organization, use the PUT /api/v1/organization/{orgname} endpoint:

    $ curl -X PUT \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
-d '{"contact_email": "new-team-alerts@example.com"}' \
"https://<quay-server.example.com>/api/v1/organization/engineering"

  • To remove the contact email, set contact_email to null or "" (empty string). System notifications default to organization owners:

    $ curl -X PUT \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
-d '{"contact_email": ""}' \
"https://<quay-server.example.com>/api/v1/organization/engineering"

  • Multiple organizations can share the same notification address (for example, a team distribution list):

    $ curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
-d '{"email": "devops-team@example.com"}' \
"https://<quay-server.example.com>/api/v1/organization/engineering"
    $ curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
-d '{"email": "devops-team@example.com"}' \
"https://<quay-server.example.com>/api/v1/organization/qa-team"
    Note

    With the default setting (FEATURE_ORG_SHARED_EMAIL: false), attempting to set an organization email to an address already registered to a user account returns Email has already been used: <email>.

    To allow the same email address to be shared across multiple organizations and with at most one user account, set FEATURE_ORG_SHARED_EMAIL: true in your config.yaml file.

Retrieving organization member information by using the API

To list organization members and collaborators or remove a member in Project Quay, you can call the organization members API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. Use the GET /api/v1/organization/{orgname}/members endpoint 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": []}]}

  2. You can use the GET /api/v1/organization/{orgname}/collaborators endpoint 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]}

  3. 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"]}

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

Additional resources

Managing an organization application by using the Project Quay API

To create, list, update, or delete organization applications in Project Quay, you can call the organization applications API endpoints with an OAuth access token.

Note

After you create an organization application in the UI, create and manage OAuth 2 access tokens from the application’s API Access Tokens page.
Prerequisites

  • You have created an OAuth access token.

Procedure

  1. 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}

  2. 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}]}

    You can also return applications for a specific client by using the GET /api/v1/organization/{orgname}/applications/{client_id} endpoint. For example:

    $ curl -X GET "https://<quay-server.example.com>/api/v1/organization/<orgname>/applications/<client_id>" \
  -H "Authorization: Bearer <access_token>"
    Example output
    {"name": "test", "description": "", "application_uri": "", "client_id": "MCJ61D8KQBFS2DXM56S2", "client_secret": "J5G7CCX5QCA8Q5XZLWGI7USJPSM4M5MQHJED46CF", "redirect_uri": "", "avatar_email": null}

  3. After creation, you can update organization applications, for example to add a redirect URI or a new description, by using the PUT /api/v1/organization/{orgname}/applications/{client_id} endpoint:

    $ curl -X PUT "https://quay-server.example.com/api/v1/organization/test/applications/12345" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Updated Application Name",
        "redirect_uri": "https://example.com/oauth/callback",
        "application_uri": "https://example.com",
        "description": "Updated description for the application",
        "avatar_email": "avatar@example.com"
      }'

  4. After creation, you can return application information by using the GET /api/v1/app/{client_id} endpoint:

    $ curl -X GET "https://<quay-server.example.com>/api/v1/app/<client_id>" \
  -H "Authorization: Bearer <access_token>"
    Example output
    {"name": "new-application3", "description": "", "uri": "", "avatar": {"name": "new-application3", "hash": "a15d479002b20f211568fd4419e76686d2b88a4980a5b4c4bc10420776c5f6fe", "color": "#aec7e8", "kind": "app"}, "organization": {"name": "test", "email": "new-contact@test-org.com", "avatar": {"name": "test", "hash": "a15d479002b20f211568fd4419e76686d2b88a4980a5b4c4bc10420776c5f6fe", "color": "#aec7e8", "kind": "user"}, "is_admin": true, "is_member": true, "teams": {}, "ordered_teams": [], "invoice_email": true, "invoice_email_address": "billing@test-org.com", "tag_expiration_s": 1209600, "is_free_account": true, "quotas": [{"id": 2, "limit_bytes": 10737418240, "limits": [{"id": 1, "type": "Reject", "limit_percent": 90}]}], "quota_report": {"quota_bytes": 0, "configured_quota": 10737418240, "running_backfill": "complete", "backfill_status": "complete"}}}

  5. You can delete organization applications with the DELETE /api/v1/organization/{orgname}/applications/{client_id} endpoint. For example:

    $ curl -X DELETE "https://<quay-server.example.com>/api/v1/organization/{orgname}/applications/{client_id}" \
  -H "Authorization: Bearer <access_token>"

    This command does not return output.

Additional resources

Configuring a proxy cache for an organization by using the Project Quay API

To create, validate, view, or delete a proxy cache configuration for an organization in Project Quay, you can call the organization proxycache API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. 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>"
        "upstream_registry_username": "your_robot_account_username"
        "upstream_registry_password": "your_robot_account_password"
      }'

  2. 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>"
        "upstream_registry_username": "your_robot_account_username"
        "upstream_registry_password": "your_robot_account_password"
      }'

  3. Use the GET /api/v1/organization/{orgname}/proxycache endpoint to obtain information about the proxy cache. For example:

    $ curl -X GET "https://<quay-server.example.com>/api/v1/organization/{orgname}/proxycache" \
  -H "Authorization: Bearer <access_token>"
    Example output
    {"upstream_registry": "quay.io", "expiration_s": 86400, "insecure": false}

  4. Use the DELETE /api/v1/organization/{orgname}/proxycache endpoint to delete the proxy cache configuration:

    $ curl -X DELETE "https://<quay-server.example.com>/api/v1/organization/{orgname}/proxycache" \
  -H "Authorization: Bearer <access_token>"
    Example output
    "Deleted"
Additional resources

Managing repository permissions by using the Project Quay API

To create, view, and delete user and team access on a repository in Project Quay, you can manage repository permissions through the API.

Managing user permissions by using the Project Quay API

To view, change, or remove a user role on a repository in Project Quay, you can call the repository user permissions API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. 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}

  2. Return all user permissions with the GET /api/v1/repository/{repository}/permissions/user/ endpoint:

    $ curl -X GET \
  -H "Authorization: Bearer <access_token>" \
  "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/user/"
    Example output
    {"permissions": {"quayadmin": {"role": "admin", "name": "quayadmin", "is_robot": false, "avatar": {"name": "quayadmin", "hash": "6d640d802fe23b93779b987c187a4b7a4d8fbcbd4febe7009bdff58d84498fba", "color": "#f7b6d2", "kind": "user"}, "is_org_member": true}, "test+example": {"role": "admin", "name": "test+example", "is_robot": true, "avatar": {"name": "test+example", "hash": "3b03050c26e900500437beee4f7f2a5855ca7e7c5eab4623a023ee613565a60e", "color": "#a1d99b", "kind": "robot"}, "is_org_member": true}}}

  3. Alternatively, 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"}]}

  4. 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}

  5. Delete user permissions by using the DELETE /api/v1/repository/{repository}/permissions/user/{username} endpoint. For example:

    $ curl -X DELETE \
  -H "Authorization: Bearer <access_token>" \
  "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/user/<username>"

    This command does not return output.

Additional resources

Managing team permissions by using the Project Quay API

To view, change, or remove a team role on a repository in Project Quay, you can call the repository team permissions API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. Return permissions for a specified team by using the GET /api/v1/repository/{repository}/permissions/team/{teamname} endpoint:

    $ curl -X GET \
  -H "Authorization: Bearer <access_token>" \
  "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/team/<teamname>"
    Example output
    {"role": "write"}

  2. Return permissions for all teams with the GET /api/v1/repository/{repository}/permissions/team/ endpoint. For example:

    $ curl -X GET \
  -H "Authorization: Bearer <access_token>" \
  "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/team/"
    Example output
    {"permissions": {"ironmanteam": {"role": "read", "name": "ironmanteam", "avatar": {"name": "ironmanteam", "hash": "8045b2361613622183e87f33a7bfc54e100a41bca41094abb64320df29ef458d", "color": "#969696", "kind": "team"}}, "sillyteam": {"role": "read", "name": "sillyteam", "avatar": {"name": "sillyteam", "hash": "f275d39bdee2766d2404e2c6dbff28fe290969242e9fcf1ffb2cde36b83448ff", "color": "#17becf", "kind": "team"}}}}

  3. Change permissions for a specified team by using the PUT /api/v1/repository/{repository}/permissions/team/{teamname} command. For example:

    $ curl -X PUT \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "<role>"}' \
  "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/team/<teamname>"
    Example output
    {"role": "admin", "name": "superteam", "avatar": {"name": "superteam", "hash": "48cb6d114200039fed5c601480653ae7371d5a8849521d4c3bf2418ea013fc0f", "color": "#9467bd", "kind": "team"}}

  4. Delete team permissions with the DELETE /api/v1/repository/{repository}/permissions/team/{teamname} command. For example:

    $ curl -X DELETE \
  -H "Authorization: Bearer <access_token>" \
  "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/permissions/team/<teamname>"

    This command does not return output in the CLI.

Additional resources

Managing auto-prune policies by using the Project Quay API

To create, retrieve, update, and delete auto-prune policies for organizations, repositories, and users in Project Quay, you can use the auto-prune policy API endpoints.

Creating an auto-prune policy for a namespace by using the Project Quay API

To create, update, view, or delete an organization auto-prune policy in Project Quay, you can use the organization autoprunepolicy API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

  • You have logged into Project Quay.

Procedure

  1. Enter the following POST /api/v1/organization/{orgname}/autoprunepolicy/ command to create a new policy that limits the number of tags allowed in an organization:

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags", "value": 10}' http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/

    Alternatively, you can set tags to expire for a specified time after their creation date:

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{
"method": "creation_date", "value": "7d"}' http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/
    Example output
    {"uuid": "73d64f05-d587-42d9-af6d-e726a4a80d6e"}

  2. 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
  }' \
  "https://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/"

    where:

    tagPatternMatches

    Specifies that the true value prunes tags that match the given regex pattern. In this example, tags that match ^v* are pruned.

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

  4. 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}]}

  5. 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
Additional resources

Creating an auto-prune policy for a namespace for the current user by using the API

To manage auto-prune policies for your own user namespace in Project Quay, you can use the /api/v1/user/autoprunepolicy/ API endpoints.

Note

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

  • You have created an OAuth access token.

  • You have logged into Project Quay.

Procedure

  1. Enter the following POST command to create a new policy that limits the number of tags for the current user:

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags", "value": 10}' http://<quay-server.example.com>/api/v1/user/autoprunepolicy/
    Example output
    {"uuid": "8c03f995-ca6f-4928-b98d-d75ed8c14859"}

  2. 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}]}

  3. 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"}

Creating an auto-prune policy for a repository using the Project Quay API

To create, update, view, or delete a repository auto-prune policy in Project Quay, you can use the repository autoprunepolicy API endpoints.

Prerequisites

  • You have created an OAuth access token.

  • You have logged into Project Quay.

Procedure

  1. Enter the following POST /api/v1/repository/<repository>/autoprunepolicy/ command to create a new policy that limits the number of tags allowed in a repository:

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags","value": 2}' http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/

    Alternatively, you can set tags to expire for a specified time after their creation date:

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "creation_date", "value": "7d"}' http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/
    Example output
    {"uuid": "ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7"}

  2. 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
  }' \
  "https://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/"

    Where:

    tagPatternMatches

    Specifies that the false value prunes tags that do not match the given regex pattern. In this example, all tags except those that match ^test. are pruned.

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

  4. 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}]}

  5. 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"}

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

To manage auto-prune policies on another user repository in Project Quay, you can use the repository autoprunepolicy API endpoints when you have admin privileges.

Prerequisites

  • You have created an OAuth access token.

  • You have logged into Project Quay.

  • You have admin privileges on the repository that you are creating the policy for.

Procedure

  1. Enter the following POST /api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/ command to create a new policy that limits the number of tags for the user:

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags","value": 2}' https://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/
    Example output
    {"uuid": "7726f79c-cbc7-490e-98dd-becdc6fefce7"}

  2. 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"}

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

  4. 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}

  5. 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"}

Creating and configuring repositories by using the Project Quay API

To create, retrieve, update, and delete repositories in Project Quay, you can use the repository API endpoints.

Creating and configuring repositories by using the Project Quay API

To create a repository and manage its visibility, details, and description in Project Quay, you can call the repository API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. Enter the following command to create a repository by 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"}

  2. You can list 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}}]}

  3. Change visibility 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}

  4. You can check the Project 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}

  5. Update repository descriptions with the PUT /api/v1/repository/{repository} endpoint:

    $ curl -X PUT \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "description": "This is an updated description for the repository."
      }' \
  "https://quay-server.example.com/api/v1/repository/<NAMESPACE>/<REPOSITORY>"
    Example output
    {"success": true}

  6. Enter the following command to delete a repository by using the DELETE /api/v1/repository/{repository} endpoint:

    $ curl -X DELETE   -H "Authorization: Bearer <bearer_token>" "<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>"

    This command does not return output in the CLI.

Additional resources

Creating notifications by using the API

To create, test, reset, or delete repository notifications in Project Quay, you can use the repository notification API endpoints.

Prerequisites

  • You have created a repository.

  • You have administrative privileges for the repository.

  • You have created an OAuth access token.

Procedure

  1. 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}

  2. 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
    {}

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

  4. 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": []}
Additional resources

Creating and configuring robot accounts by using the Project Quay API

To create, retrieve, update, and delete robot accounts for organizations and users in Project Quay, you can use the robot account API endpoints.

Creating a robot account by using the Project Quay API

To automate access to your repositories, you can create a robot account by using the Project Quay API. You can create robot accounts for an organization or for your own user account.

Prerequisites

  • You have created an OAuth access token.

Procedure

  • Enter the following command to create a new robot account for an organization by using the PUT /api/v1/organization/{orgname}/robots/{robot_shortname} endpoint:

    $ curl -X PUT   -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/organization/<organization_name>/robots/<robot_name>"
    Example output
    {"name": "orgname+robot-name", "created": "Fri, 10 May 2024 15:11:00 -0000", "last_accessed": null, "description": "", "token": "<example_secret>", "unstructured_metadata": null}

  • Enter the following command to create a new robot account for the current user with the PUT /api/v1/user/robots/{robot_shortname} endpoint:

    $ curl -X PUT   -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/user/robots/<robot_name>"
    Example output
    {"name": "quayadmin+robot-name", "created": "Fri, 10 May 2024 15:24:57 -0000", "last_accessed": null, "description": "", "token": "<example_secret>", "unstructured_metadata": null}
Additional resources

Obtaining robot account information by using the Project Quay API

To review robot account details and permissions for an organization or user in Project Quay, you can call the robot account API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  • Use the GET /api/v1/organization/{orgname}/robots/{robot_shortname} API endpoint to return information for a robot for an organization:

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  "https://quay-server.example.com/api/v1/organization/<ORGNAME>/robots/<ROBOT_SHORTNAME>"
    Example output
    {"name": "test+example", "created": "Mon, 25 Nov 2024 16:25:16 -0000", "last_accessed": null, "description": "", "token": "string", "unstructured_metadata": {}}

  • Use the GET /api/v1/organization/{orgname}/robots/{robot_shortname}/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": "<token_example>", "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"}]}
Additional resources

Deleting a robot account by using the Project Quay API

To remove a robot account that you no longer need, you can delete it by using the Project Quay API. You can delete robot accounts that belong to an organization or to your own user account.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. Enter the following command to delete a robot account for an organization by using the DELETE /api/v1/organization/{orgname}/robots/{robot_shortname} endpoint:

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

  2. The CLI does not return information when deleting a robot account with the API. To confirm deletion, you can check the Project 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": []}

  3. 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>"

  4. 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 Project 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"}
Additional resources

Searching against registry context

To find repositories, entities, and other registry resources in Project Quay, you can use the search API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  • Use the GET /api/v1/find/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"}}]}
Additional resources

Viewing Clair security scans by using the API

To view Clair security scan results for a repository manifest in Project Quay, you can call the manifest security API endpoint with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  • Use the GET /api/v1/repository/{repository}/manifest/{manifestref}/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}
Additional resources

Managing your deployment as a superuser with the Project Quay API

To create, list, change, and delete users, service keys, quotas, and other registry resources as a superuser in Project Quay, you can use the Project Quay API.

Creating a user account by using the Project Quay API

To create a user account in Project Quay as a superuser, you can use the Project Quay API.

Prerequisites

  • You are logged into your Project Quay deployment as a superuser.

  • You have created an OAuth access token.

Procedure

  1. Enter the following command to create a new user by using the POST /api/v1/superuser/users/ endpoint:

    $ curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" -d '{
  "username": "newuser",
  "email": "newuser@example.com"
}' "https://<quay-server.example.com>/api/v1/superuser/users/"
    Example output
    {"username": "newuser", "email": "newuser@example.com", "password": "123456789", "encrypted_password": "<example_encrypted_password>/JKY9pnDcsw="}

  2. Navigate to your Project Quay registry endpoint, for example, quay-server.example.com and log in 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

  3. 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}]}
Additional resources

Deleting a user by using the Project Quay API

To delete a user account from Project Quay as a superuser, you can use the Project Quay API.

Important

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

  • You are logged into your Project Quay deployment as a superuser.

  • You have created an OAuth access token.

Procedure

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

  2. The CLI does not return information when deleting a user from the CLI. To confirm deletion, you can check the Project 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/"
Additional resources

Managing organizations as a superuser with the Project Quay API

To list, update, or delete organizations in Project Quay, you can use the superuser organization API endpoints.

Prerequisites

  • You have created an OAuth access token.

  • You are logged into your Project Quay deployment as a superuser.

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 an organization:

    $ curl -X DELETE \
  -H "Authorization: Bearer <bearer_token>" \
  "https://<quay_server>/api/v1/superuser/organizations/<organization_name>"

    This command does not return output in the CLI.

Additional resources

Listing logs as a superuser with the Project Quay API

To list usage logs or obtain registry size information in Project Quay, you can use the superuser logs and registry size API endpoints.

Prerequisites

  • You have created an OAuth access token.

  • You are logged into your Project Quay deployment as a superuser.

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/ endpoint to obtain information about the size of the registry:

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  "https://<quay_server>/api/v1/superuser/registrysize/"
    Example output
    {"size_bytes": 0, "last_ran": null, "running": false, "queued": false}

  • Use the POST /api/v1/superuser/registrysize/ endpoint to define registry size information:

    $ curl -X POST "https://quay-server.example.com/api/v1/superuser/registrysize/" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "<namespace>",
    "last_ran": 1700000000,
    "queued": true,
    "running": false
  }'

    This command does not return output in the CLI.

Additional resources

Managing organization quota with the Project Quay API

To create, view, update, or delete organization quota policies in Project Quay, you can use the superuser organization quota API endpoints.

Prerequisites

  • You have created an OAuth access token.

  • You are logged into your Project Quay deployment as a superuser.

Procedure

  1. 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"

  2. 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}]

  3. 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}

  4. Use the DELETE /api/v1/superuser/organization/{namespace}/quota/{quota_id} API endpoint to delete a quota policy for an organization:

    $ curl -X DELETE "https://quay-server.example.com/api/v1/superuser/organization/<namespace>/quota/<quota_id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

    This command does not return output in the CLI.

Additional resources

Managing user quota with the Project Quay API

To create, view, update, or delete user quota policies in Project Quay, you can use the superuser user quota API endpoints.

Prerequisites

  • You have created an OAuth access token.

  • You are logged into your Project Quay deployment as a superuser.

Procedure

  1. 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"

  2. 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}]

  3. 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}

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

Additional resources

Retrieving build information with the Project Quay API

To retrieve build details, status, and logs as a Project Quay superuser, you can use the superuser build API endpoints.

Prerequisites

  • You have created an OAuth access token.

  • You have superuser privileges.

Procedure

  1. Enter the following command to return information about a build by using the GET /api/v1/superuser/{build_uuid}/build endpoint:

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

  2. Enter the following command to return the status for builds that you specify by UUID by using the GET /api/v1/superuser/{build_uuid}/status endpoint:

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

  3. Enter the following command to return the build logs for a build that you specify by UUID by using the GET /api/v1/superuser/{build_uuid}/logs endpoint:

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

Managing service keys as a superuser with the Project Quay API

To create, list, approve, update, or delete service keys as a Project Quay superuser, you can use the superuser keys API endpoints.

Prerequisites

  • You have created an OAuth access token.

  • You have superuser privileges.

Procedure

  • Enter the following command to create a service key by using the POST /api/v1/superuser/keys endpoint:

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "service": "<service_name>",
        "expiration": <unix_timestamp>
      }' \
  "<quay_server>/api/v1/superuser/keys"
    Example output
    {"message":""}

  • Enter the following command to approve a service key by using the POST /api/v1/superuser/approvedkeys/{kid} endpoint:

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "notes": "<approval_notes>"
      }' \
  "https://<quay_server>/api/v1/superuser/approvedkeys/<kid>"

    This command does not return output in the CLI.

  • Enter the following command to list service keys by using the GET /api/v1/superuser/keys endpoint:

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  "https://<quay_server>/api/v1/superuser/keys"
    Example output
    {"keys":[{"approval":{"approval_type":"ServiceKeyApprovalType.AUTOMATIC","approved_date":"Mon, 20 Jan 2025 14:46:01 GMT","approver":null,"notes":""},"created_date":"Mon, 20 Jan 2025 14:46:01 GMT","expiration_date":"Wed, 05 Feb 2025 22:03:37 GMT","jwk":{"e":"AQAB","kid":"<example>","kty":"RSA","n":"<example>"},"kid":"7fr8soqXGgea8JqjwgItjjJT9GKlt-bMyMCDmvzy6WQ","metadata":{"created_by":"CLI tool"},"name":"http://quay-server.example.com:80","rotation_duration":null,"service":"quay"}]}

  • Enter the following command to return a list of service account keys by using the GET /api/v1/superuser/apptokens endpoint:

    $ curl -X GET \
  "https://quay-server.example.com/api/v1/superuser/apptokens" \
  -H "Authorization: Bearer <superuser_access_token>" \
  -H "Accept: application/json"

    Alternatively, you can include the expiring=true option. For example:

    $ curl -X GET \
  "https://quay-server.example.com/api/v1/superuser/apptokens?expiring=true" \
  -H "Authorization: Bearer <superuser_access_token>" \
  -H "Accept: application/json"

  • Enter the following command to retrieve information about a service account by its kid by using the GET /api/v1/superuser/keys/{kid} endpoint:

    $ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  "https://<quay_server>/api/v1/superuser/keys/<kid>"
    Example output
    {"approval":{"approval_type":"ServiceKeyApprovalType.AUTOMATIC","approved_date":"Mon, 20 Jan 2025 14:46:01 GMT","approver":null,"notes":""},"created_date":"Mon, 20 Jan 2025 14:46:01 GMT","expiration_date":"Wed, 05 Feb 2025 22:03:37 GMT","jwk":{"e":"AQAB","kid":"7fr8soqXGgea8JqjwgItjjJT9GKlt-bMyMCDmvzy6WQ","kty":"RSA","n":"5iMX7RQ_4F_zdb1qonMsuWUDauCOqEyRpD8L_EhgnwDxrgMHuOlJ4_7sEOrOa3Jkx3QhwIW6LJCP69PR5X0wvz6vmC1DoWEaWv41bAq23Knzj7gUU9-N_fkZPZN9NQwZ-D-Zqg9L1c_cJF93Dy93py8_JswWFDj1FxMaThJmrX68wBwjhF-JLYqgCAGFyezzJ3oTpO-esV9v6R7skfkaqtx_cjLZk_0cKB4VKTtxiy2A8D_5nANTOSSbZLXNh2Vatgh3yrOmnTTNLIs0YO3vFIuylEkczHlln-40UMAzRB3HNspUySyzImO_2yGdrA762LATQrOzJN8E1YKCADx5CQ"},"kid":"7fr8soqXGgea8JqjwgItjjJT9GKlt-bMyMCDmvzy6WQ","metadata":{"created_by":"CLI tool"},"name":"http://quay-server.example.com:80","rotation_duration":null,"service":"quay"}

  • Enter the following command to update your service key, such as the metadata, by using the PUT /api/v1/superuser/keys/{kid} endpoint:

    $ curl -X PUT \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "<service_key_name>",
        "metadata": {"<key>": "<value>"},
        "expiration": <unix_timestamp>
      }' \
  "https://<quay_server>/api/v1/superuser/keys/<kid>"
    Example output
    {"approval":{"approval_type":"ServiceKeyApprovalType.AUTOMATIC","approved_date":"Mon, 20 Jan 2025 14:46:01 GMT","approver":null,"notes":""},"created_date":"Mon, 20 Jan 2025 14:46:01 GMT","expiration_date":"Mon, 03 Mar 2025 10:40:00 GMT","jwk":{"e":"AQAB","kid":"7fr8soqXGgea8JqjwgItjjJT9GKlt-bMyMCDmvzy6WQ","kty":"RSA","n":"5iMX7RQ_4F_zdb1qonMsuWUDauCOqEyRpD8L_EhgnwDxrgMHuOlJ4_7sEOrOa3Jkx3QhwIW6LJCP69PR5X0wvz6vmC1DoWEaWv41bAq23Knzj7gUU9-N_fkZPZN9NQwZ-D-Zqg9L1c_cJF93Dy93py8_JswWFDj1FxMaThJmrX68wBwjhF-JLYqgCAGFyezzJ3oTpO-esV9v6R7skfkaqtx_cjLZk_0cKB4VKTtxiy2A8D_5nANTOSSbZLXNh2Vatgh3yrOmnTTNLIs0YO3vFIuylEkczHlln-40UMAzRB3HNspUySyzImO_2yGdrA762LATQrOzJN8E1YKCADx5CQ"},"kid":"7fr8soqXGgea8JqjwgItjjJT9GKlt-bMyMCDmvzy6WQ","metadata":{"created_by":"CLI tool","environment":"production"},"name":"quay-service-key-updated","rotation_duration":null,"service":"quay"}

  • Enter the following command to delete a service key by using the DELETE /api/v1/superuser/keys/{kid} endpoint:

    $ curl -X DELETE \
  -H "Authorization: Bearer <bearer_token>" \
  "https://<quay_server>/api/v1/superuser/keys/<kid>"

    This command does not return output in the CLI.

Additional resources

Managing tags with the Project Quay API

To change, restore, list, or delete repository tags in Project Quay, you can use the tag API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. 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"

  2. 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
    {}

  3. 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}

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

Additional resources

Managing teams by using the API

Organization teams in Project Quay group users for shared repository access. You can manage teams and membership by using the API.

Managing team members and repository permissions by using the API

To add, invite, or remove members of an organization team in Project Quay, you can use the team member API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  • Enter the PUT /api/v1/organization/{orgname}/team/{teamname}/members/{membername} command to add or invite a member to an existing team:

    $ curl -X PUT \
  -H "Authorization: Bearer <your_access_token>" \
  "<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>/members/<member_name>"
    Example output
    {"name": "testuser", "kind": "user", "is_robot": false, "avatar": {"name": "testuser", "hash": "d51d17303dc3271ac3266fb332d7df919bab882bbfc7199d2017a4daac8979f0", "color": "#5254a3", "kind": "user"}, "invited": false}

  • Enter the DELETE /api/v1/organization/{orgname}/team/{teamname}/members/{membername} command to remove a member of a team:

    $ curl -X DELETE \
  -H "Authorization: Bearer <your_access_token>" \
  "<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>/members/<member_name>"

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

Setting the role of a team within an organization by using the API

To view repository permissions for a team or set a team’s role in an Project Quay organization, you can use the organization team API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. 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"}]}

  2. 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}
Additional resources

Deleting a team within an organization by using the API

To delete a team from an organization in Project Quay, you can use the organization team API endpoint with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  • You can delete a team within an organization by entering the DELETE /api/v1/organization/{orgname}/team/{teamname} command:

    $ curl -X DELETE \
  -H "Authorization: Bearer <your_access_token>" \
  "<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>"

    This command does not return output in the CLI.

Additional resources

Managing builds by using the Project Quay API

To list, activate, start, update, or delete build triggers in Project Quay, you can use the build trigger API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. 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}]}

  2. 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"
  }'

  3. 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"
  }'

  4. 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>"

  5. 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>"

  6. 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}'

  7. 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>"
Additional resources

Managing current user options by using the Project Quay API

To retrieve account information or star and unstar repositories in Project Quay, you can use the user API endpoints with an OAuth access token.

Prerequisites

  • You have created an OAuth access token.

Procedure

  1. 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}

  2. 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}

  3. 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"}

  4. 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}]}

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

Additional resources