SupportConsoleDevelopersStart a trialContact

Chapter 10. mirror

Mirror.

10.1. syncCancel
Copy link

Update the sync_status for a given Repository’s mirroring configuration.

Authorizations: oauth2_implicit (repo:admin)

10.1.2. Path parameters
Copy link

TypeNameDescriptionSchema

path

repository

required

The full path of the repository. e.g. namespace/name

string

10.1.3. Responses
Copy link

HTTP CodeDescriptionSchema

201

Successful creation

 

400

Bad Request

ApiError

401

Session required

ApiError

403

Unauthorized access

ApiError

404

Not found

ApiError

10.1.4. Example command
Copy link

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

10.2. syncNow
Copy link

Update the sync_status for a given Repository’s mirroring configuration.

Authorizations: oauth2_implicit (repo:admin)

10.2.2. Path parameters
Copy link

TypeNameDescriptionSchema

path

repository

required

The full path of the repository. e.g. namespace/name

string

10.2.3. Responses
Copy link

HTTP CodeDescriptionSchema

201

Successful creation

 

400

Bad Request

ApiError

401

Session required

ApiError

403

Unauthorized access

ApiError

404

Not found

ApiError

10.2.4. Example command
Copy link

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

10.3. getRepoMirrorConfig
Copy link

Return the Mirror configuration for a given Repository.

10.3.1. GET /api/v1/repository/{repository}/mirror
Copy link

Authorizations: oauth2_implicit (repo:admin)

10.3.2. Path parameters
Copy link

TypeNameDescriptionSchema

path

repository

required

The full path of the repository. e.g. namespace/name

string

10.3.3. Responses
Copy link

HTTP CodeDescriptionSchema

200

Successful invocation

ViewMirrorConfig

400

Bad Request

ApiError

401

Session required

ApiError

403

Unauthorized access

ApiError

404

Not found

ApiError

10.3.4. Example command
Copy link

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

10.4. changeRepoMirrorConfig
Copy link

Allow users to modifying the repository’s mirroring configuration.

10.4.1. PUT /api/v1/repository/{repository}/mirror
Copy link

Authorizations: oauth2_implicit (repo:admin)

10.4.2. Path parameters
Copy link

TypeNameDescriptionSchema

path

repository

required

The full path of the repository. e.g. namespace/name

string

10.4.3. Request body schema (application/json)
Copy link

Update the repository mirroring configuration.

NameDescriptionSchema

is_enabled

optional

Used to enable or disable synchronizations.

boolean

external_reference

optional

Location of the external repository.

string

external_registry_username

optional

Username used to authenticate with external registry.

 

external_registry_password

optional

Password used to authenticate with external registry.

 

sync_start_date

optional

Determines the next time this repository is ready for synchronization.

string

sync_interval

optional

Number of seconds after next_start_date to begin synchronizing.

integer

robot_username

optional

Username of robot which will be used for image pushes.

string

root_rule

optional

A list of glob-patterns used to determine which tags should be synchronized.

object

external_registry_config

optional

 

object

skopeo_timeout_interval

required

Number of seconds mirroring job will run before timing out.

Integer

10.4.4. Responses
Copy link

HTTP CodeDescriptionSchema

201

Successful invocation

 

400

Bad Request

ApiError

401

Session required

ApiError

403

Unauthorized access

ApiError

404

Not found

ApiError

10.4.5. Example command
Copy link

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

10.5. createRepoMirrorConfig
Copy link

Create a RepoMirrorConfig for a given Repository.

Authorizations: oauth2_implicit (repo:admin)

10.5.2. Path parameters
Copy link

TypeNameDescriptionSchema

path

repository

required

The full path of the repository. e.g. namespace/name

string

10.5.3. Request body schema (application/json)
Copy link

Create the repository mirroring configuration.

NameDescriptionSchema

is_enabled

optional

Used to enable or disable synchronizations.

boolean

external_reference

required

Location of the external repository.

string

external_registry_username

optional

Username used to authenticate with external registry.

 

external_registry_password

optional

Password used to authenticate with external registry.

 

sync_start_date

required

Determines the next time this repository is ready for synchronization.

string

sync_interval

required

Number of seconds after next_start_date to begin synchronizing.

integer

robot_username

required

Username of robot which will be used for image pushes.

string

root_rule

required

A list of glob-patterns used to determine which tags should be synchronized.

object

external_registry_config

optional

 

object

skopeo_timeout_interval

required

Number of seconds mirroring job will run before timing out.

Integer

10.5.4. Responses
Copy link

HTTP CodeDescriptionSchema

201

Successful creation

 

400

Bad Request

ApiError

401

Session required

ApiError

403

Unauthorized access

ApiError

404

Not found

ApiError

10.5.5. Example command
Copy link

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

10.6. getRepositoryMirrorHealth
Copy link

Return health status for repository mirroring operations.

10.6.1. GET /api/v1/repository/mirror/health
Copy link

Authorizations: oauth2_implicit (super:user for global queries; organization membership or user administration for namespace-scoped queries)

Returns HTTP 200 when mirroring is healthy and HTTP 503 when unhealthy.

This endpoint requires a fresh login. A validated OAuth or SSO token satisfies the check. A password-based browser session must be within FRESH_LOGIN_TIMEOUT (default: 10m). Robot accounts cannot call this endpoint.

Access control:

  • Without the namespace query parameter, the caller must be a superuser with full access, or a global read-only superuser.
  • With namespace, organization members can query their organization. For a user namespace, the caller must be that user or have user-admin permission. Superusers can query any namespace.

For a global summary without per-repository samples, superusers can also call GET /api/v1/superuser/mirror/health. See getSuperUserRepositoryMirrorHealth.

10.6.2. Query parameters
Copy link

TypeNameDescriptionSchema

query

namespace

optional

Filter the health check to a specific namespace

string

query

detailed

optional

Include per-repository breakdown

boolean

query

limit

optional

Maximum repositories in the detailed response when detailed=true (default: 100, max: 1000)

integer

query

offset

optional

Offset into the sorted mirror list for paginated details (default: 0)

integer

10.6.3. Responses
Copy link

HTTP CodeDescriptionSchema

200

Mirroring is healthy

object

401

Session required

ApiError

403

Unauthorized access

ApiError

404

Namespace not found

ApiError

503

Mirroring is unhealthy

object

10.6.4. Example commands
Copy link

Query health for a namespace that you can administer. Include detailed=true for a per-repository breakdown: 

$ curl -X GET "https://<quay-server.example.com>/api/v1/repository/mirror/health?namespace=<orgname>&detailed=true" \
     -H "Authorization: Bearer <access_token>"

Query global mirror health as a superuser with full access: 

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

Substitute an OAuth access token that includes the super:user scope for global queries. For namespace-scoped queries, use a token or fresh login session for an organization member or namespace administrator.

Example output

{
  "healthy": true,
  "workers": {
    "active": 1,
    "configured": 1,
    "status": "healthy"
  },
  "repositories": {
    "total": 0,
    "syncing": 0,
    "completed": 0,
    "failed": 0,
    "never_run": 0,
    "details": [],
    "pagination": {
      "limit": 100,
      "offset": 0,
      "has_more": false
    }
  },
  "tags_pending": 0,
  "last_check": "2026-07-16T20:11:54.820064Z",
  "issues": []
}

For metric names, example Prometheus queries, and health determination logic, see Monitoring repository mirroring.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top