Skip to main content

OCI Repositories API

OCI repository APIs manage space and project-scoped OCI repositories, access settings, Docker/Helm registry token auth, artifact metadata, and public registry import jobs.

info

All endpoints are mounted under /api/v1.0. Paths below omit that prefix for readability.

The API requires the packages.oci_registry feature key.

Repository Management​

MethodEndpointDescription
GET/spaces/{slug}/oci-project-scopesList project scopes.
POST/spaces/{slug}/oci-project-scopesCreate a project scope.
PATCH/spaces/{slug}/oci-project-scopes/{project_scope_id}Update a project scope.
GET/spaces/{slug}/oci-project-scopes/{project_scope_id}/accessRead project-scope access settings.
PUT/spaces/{slug}/oci-project-scopes/{project_scope_id}/accessReplace project-scope access settings.
GET/spaces/{slug}/oci-repositoriesList repositories.
POST/spaces/{slug}/oci-repositoriesCreate a repository.
GET/spaces/{slug}/oci-repositories/{repository_id}Read repository detail with artifacts.
PATCH/spaces/{slug}/oci-repositories/{repository_id}Update repository metadata or active/archive flags.
POST/spaces/{slug}/oci-repositories/{repository_id}/archiveArchive a repository.
DELETE/spaces/{slug}/oci-repositories/{repository_id}/artifacts/{artifact_name}/references/{reference}Delete an artifact tag or digest reference.

Space-wide repositories use oci_registry_repository permissions. Project scopes can inherit space role access or use direct user/team grants.

Registry Token​

Docker and Helm clients authenticate through the OCI token endpoint:

GET /oci/token

The endpoint accepts Docker registry token parameters and returns:

{
  "token": "registry-token",
  "access_token": "registry-token",
  "expires_in": 900,
  "issued_at": "2026-06-22T08:00:00Z"
}

Use Qarion API keys as the client credential and __token__ as the Docker or Helm username.

GET /spaces/{slug}/oci-repositories/{repository_id}/imports/public-registry/search?artifact_kind=docker&q=nginx&limit=5

artifact_kind is docker or helm. Docker search targets Docker Hub. Helm search targets Artifact Hub and returns importable OCI references when package metadata exposes them. Search requires push access because it is part of the import workflow.

Search Response​

{
  "query": "nginx",
  "artifact_kind": "docker",
  "results": [
    {
      "provider": "docker_hub",
      "name": "nginx",
      "repository": "library/nginx",
      "description": "Official build of Nginx.",
      "detail_url": "https://hub.docker.com/_/nginx",
      "badges": ["official"],
      "metadata": {},
      "references": [
        {
          "label": "latest",
          "source_reference": "nginx:latest",
          "digest": null,
          "media_type": null,
          "size_bytes": null,
          "last_updated": null,
          "app_version": null
        }
      ]
    }
  ],
  "warnings": []
}

Public Registry Import​

Imports are asynchronous because the worker must fetch manifests and blobs from the public registry and store them in the Qarion repository.

POST /spaces/{slug}/oci-repositories/{repository_id}/imports/public-registry
{
  "source_reference": "nginx:1.27",
  "artifact_kind": "docker",
  "destination_artifact_name": "mirrors/nginx",
  "destination_reference": "1.27"
}

source_reference must be exact and must include a tag or digest. Docker references can use Docker Hub shorthand such as nginx:1.27 or an explicit registry host. Helm imports must use oci:// references such as oci://registry-1.docker.io/bitnamicharts/nginx:18.2.5.

destination_artifact_name and destination_reference are optional overrides. When omitted, Qarion derives the destination artifact name and tag or digest from the source reference.

The create response is:

{
  "job_id": "job-uuid"
}

Import Job Status​

GET /spaces/{slug}/oci-repositories/{repository_id}/imports/public-registry/jobs/{job_id}
{
  "job_id": "job-uuid",
  "status": "completed",
  "percent": 100,
  "phase": "completed",
  "message": "OCI import completed",
  "progress_events": [],
  "result": {
    "source_reference": "nginx:1.27",
    "artifact_kind": "docker",
    "destination_artifact_name": "mirrors/nginx",
    "destination_reference": "1.27",
    "manifest_digest": "sha256:...",
    "artifact_type": "container_image",
    "manifest_count": 1,
    "blob_count": 6,
    "skipped_blob_count": 2
  },
  "error_message": null
}

Import jobs run on the arq:bulk queue through import_oci_artifact_from_public_registry. External worker deployments must run a bulk worker or the priority worker supervisor.

Error Notes​

StatusMeaning
403The user lacks view, push, edit, admin, or delete access for the repository or project scope.
404Repository, project scope, artifact, reference, or job was not found or is inaccessible.
422Source reference, destination override, or artifact kind is invalid.
503The import queue is unavailable or a public registry fetch failed.