Skip to content
Open Console →

Registries

22 endpoints under /api/v1/registry.

GET /api/v1/registry/upstreams #

The pull-through cache catalog (what you may cache)

Responses

200 Cacheable upstreams.
Response body
  • upstreamsRegistryUpstream[]required
    Show fields
    • hoststringrequired
    • endpointstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/registry/registries #

List the org's registries

Responses

200 The org's registries (instance-filtered for scoped subjects).
Response body
  • registriesRegistry[]required
    Show fields
    • slugstringrequired
    • displayNamestringrequired
    • regionstringrequired
    • storageQuotaBytesintegerrequired
    • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/registry/registries #

Create a registry

The slug is globally unique and immutable. Requires an active payment method (ADR 0051 §8). 409 when the slug is taken or reserved.

Request body

  • slugstringrequired
  • displayNamestring
  • regionstring

Responses

201 Registry created.
Response body
  • slugstringrequired
  • displayNamestringrequired
  • regionstringrequired
  • storageQuotaBytesintegerrequired
  • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
402 No active payment method.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
409 Slug taken or reserved.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/registry/registries/{slug} #

One registry, with quota + logical usage

Parameters

  • slug path string required

Responses

200 The registry.
Response body
  • slugstringrequired
  • regionstringrequired
  • storageQuotaBytesintegerrequired
  • usedBytesintegerrequired
  • repositoryCountintegerrequired
  • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/registry/docker-credential #

Mint a short-lived org docker-login credential

For `lbr registry login` / the docker credential-helper (ADR 0051 §3): one 1h credential authorizing every registry you can reach, minted on demand and cached client-side. `registry` narrows it to one; `pullOnly` downgrades to read-only. 403 if you have no registry access.

Request body

  • registrystring
  • pullOnlyboolean

Responses

201 A short-lived org docker credential.
Response body
  • usernamestringrequired
  • passwordstringrequired
  • expiresAtstringrequired
  • registrystringrequired
  • scopeobject[]required
    Show fields
    • registrystringrequired
    • modestring · enumrequired

      pullreadwrite

401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/registry/registries/{slug} #

Delete a registry

Parameters

  • slug path string required

Responses

204 Deleted.
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
409 The registry has repositories — delete them first.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/registry/registries/{slug}/tags #

List a repository's tags

Parameters

  • slug path string required
  • repo query string required

Responses

200 Tags.
Response body
  • tagsRegistryTag[]required
    Show fields
    • namestringrequired
    • digeststringrequired
    • manifestSizeintegerrequired
    • updatedAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/registry/registries/{slug}/keys #

List registry keys (metadata only — never a secret)

Parameters

  • slug path string required

Responses

200 The registry's keys.
Response body
  • keysRegistryKey[]required
    Show fields
    • keyIdstringrequired
    • namestringrequired
    • modestring · enumrequired

      pullreadwrite

    • repoPrefixesstring[]required
    • mintedViastring · enumrequired

      manualoidc

    • createdAtstringrequired
    • expiresAtstring
    • lastUsedAtstring
    • revokedAtstring
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/registry/registries/{slug}/keys #

Mint a registry key

The plaintext secret is returned ONCE (docker login password). Minting a long-lived data-plane credential is admin-tier (registry.key.admin).

Parameters

  • slug path string required

Request body

  • namestringrequired
  • modestring · enumrequired

    pullreadwrite

  • repoPrefixesstring[]

Responses

201 Key minted; the secret appears only here.
Response body
  • keyIdstringrequired
  • secretstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/registry/registries/{slug}/tags #

Delete a tag

Removes the tag only; the manifest and its blobs remain as an untagged manifest. With purge=true, if the tag was the manifest's last, the now-orphaned image is deleted too and its space reclaimed (admin-tier).

Parameters

  • slug path string required
  • repo query string required
  • tag query string required
  • purge query string · enum

Responses

200 Deleted; `purged` is true when an orphaned image was also removed.
Response body
  • purgedbooleanrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/registry/docker-credential/{keyId} #

Revoke an org docker-login credential (logout)

Parameters

  • keyId path string required

Responses

204 Revoked.
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/registry/registries/{slug}/manifests #

List a repository's manifests (tagged and untagged)

Parameters

  • slug path string required
  • repo query string required

Responses

200 Manifests.
Response body
  • manifestsRegistryManifest[]required
    Show fields
    • digeststringrequired
    • mediaTypestringrequired
    • sizeBytesintegerrequired
    • tagsstring[]required
    • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/registry/registries/{slug}/manifests #

Delete one image by digest (tagged or untagged)

Removes the manifest and its tags; blobs no longer referenced by the repository are freed to garbage collection. Use this to clean up untagged images without deleting the whole repository.

Parameters

  • slug path string required
  • repo query string required
  • digest query string required

Responses

204 Deleted.
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/registry/registries/{slug}/oidc-rules #

List OIDC access rules

Parameters

  • slug path string required

Responses

200 The rules.
Response body
  • rulesRegistryOidcRule[]required
    Show fields
    • idintegerrequired
    • namestringrequired
    • issuerstringrequired
    • audiencestringrequired
    • subjectPatternstringrequired
    • modestring · enumrequired

      pullreadwrite

    • repoPrefixesstring[]required
    • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/registry/registries/{slug}/oidc-rules #

Create an OIDC access rule

CI trades an OIDC ID token (issuer + audience + subject pattern) for a short-lived registry key — no long-lived push secret in CI.

Parameters

  • slug path string required

Request body

  • namestring
  • issuerstring · urirequired
  • audiencestringrequired
  • subjectPatternstringrequired
  • modestring · enumrequired

    pullreadwrite

  • repoPrefixesstring[]

Responses

201 Rule created.
Response body
  • idintegerrequired
  • namestringrequired
  • issuerstringrequired
  • audiencestringrequired
  • subjectPatternstringrequired
  • modestring · enumrequired

    pullreadwrite

  • repoPrefixesstring[]required
  • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/registry/registries/{slug}/repositories #

List a registry's repositories

Parameters

  • slug path string required

Responses

200 Repositories.
Response body
  • repositoriesRegistryRepository[]required
    Show fields
    • namestringrequired
    • tagCountintegerrequired
    • sizeBytesintegerrequired
    • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/registry/registries/{slug}/repositories #

Delete a repository

Removes every manifest (tagged AND untagged), its tags, and its blobs (freed to garbage collection). Empty a registry this way before deleting it.

Parameters

  • slug path string required
  • repo query string required

Responses

204 Deleted.
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/registry/registries/{slug}/keys/{keyId} #

Revoke a registry key

Parameters

  • slug path string required
  • keyId path string required

Responses

204 Revoked.
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/registry/registries/{slug}/oidc-rules/{id} #

Delete an OIDC access rule

Parameters

  • slug path string required
  • id path integer

Responses

204 Deleted.
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/registry/registries/{slug}/upstream-credentials #

List BYO upstream credentials (username + presence only)

Parameters

  • slug path string required

Responses

200 Configured upstream credentials.
Response body
  • upstreamCredentialsRegistryUpstreamCredential[]required
    Show fields
    • upstreamstringrequired
    • usernamestringrequired
    • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
PUT /api/v1/registry/registries/{slug}/upstream-credentials/{host} #

Set a BYO upstream credential

The customer's own login for a catalog upstream (e.g. private Docker Hub). Their pulls ride their rate limits; cached content is org-scoped.

Parameters

  • slug path string required
  • host path string required

Request body

  • usernamestringrequired
  • passwordstringrequired

Responses

200 Stored.
Response body
  • upstreamstringrequired
  • usernamestringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/registry/registries/{slug}/upstream-credentials/{host} #

Delete a BYO upstream credential

Parameters

  • slug path string required
  • host path string required

Responses

204 Deleted.
401 No valid session.
Response body
  • errorstringrequired
403 Registry is not enabled for this organization (private beta), or the acting subject lacks the required Registry permission (possibly on this Registry).
Response body
  • errorstringrequired
404 Unknown resource.
Response body
  • errorstringrequired
502 The Registry service is unreachable.
Response body
  • errorstringrequired