Finding a chart
GET /api/artifacthub/search?q=<term> proxies ArtifactHub’s package search, restricted to Helm charts, sorted by relevance, up to 50 results. Responses are cached, so repeated searches for the same term are free.
repository.url is what goes into an app definition’s helmRepoUrl, deprecated rules out charts that will stop receiving updates, and verified_publisher plus signatures say how much the source is worth trusting. version is the chart version, app_version the software inside it — the app definition wants the former.
Search is a discovery aid, not a validation step. Once you have a repo URL and chart name, confirm the exact version exists with POST /api/apps/helm-check before saving the definition.
Platform chart versions
GET /api/charts/versions?source=<key> answers “what can this platform component be upgraded to”. source is a catalogue key, not a chart name — cilium, cert-manager, monitoring, rook-operator, rook-cluster, nfs, external-secrets, cluster-api-operator, vcluster, loki, alloy, frr-k8s, and the rest. Omitting it, or passing an unknown key, returns 400 with the valid keys listed.
The response is what every version dropdown in the onboarding wizard renders:
An unreachable upstream does not fail the call. The endpoint returns
200 with an empty versions array and a note explaining the fetch failure, so a wizard step degrades to “no update info available” instead of erroring the whole page. If a picker is empty, read note first — it usually names the cause outright.Mirror status
GET /api/charts/mirror-status is the platform-wide view: for every catalogue chart, where it resolves from right now and what the daily version worker last saw.
When no default chart registry is configured, the response has no
registry block and every row shows source: "upstream" — the platform installs each chart straight from its public source. Configure one and the response gains registry, registryId and repoUrl, and rows flip to internal as charts get stocked.
KubeVirt and CDI are absent from this list on purpose. They are mirrored as operator images, not Helm charts, so their state belongs to the pre-pull image inventory rather than the chart table.
When a version list is empty or a pull fails
Mirror status is the first stop, because it separates “the platform cannot see any versions” from “the platform can see them but cannot fetch them”.1
Read the row for that chart
A populated
latestUpstream means discovery works and the problem is downstream. An empty one with a lastError means the worker itself could not read the source — that error is usually the whole answer.2
Check where it resolves from
source: "internal" with an empty mirroredVersion is the classic empty-picker case: installs are pointed at the mirror and the mirror has nothing. Either stock the chart or set that chart’s override to upstream.3
Suspect the registry credentials
When
GET /api/charts/versions comes back with a note about unreadable mirror stock, the registry is reachable but the credentials cannot list tags. Test them under Settings → Registries — a pull-only credential lists fine, a wrong one does not.4
Only then look at the chart itself
lastError: "no stable version found" on an OCI source means the tags exist but none parse as a stable release — common for charts whose tags are not plain semver. Installs still work with an explicit version; only the “latest” nudge is unavailable.GET /api/supervisors/<supervisor>/flux/status and the HelmRelease’s own conditions, which the component-status model surfaces per component.
Permissions
Both chart reads share one action, so mirror status and version lists are granted together — they answer the same question from opposite ends.
Related
App catalog
Turning a search result into a definition, and validating the chart before saving.
GitOps overview
Where Flux reconciles the charts these versions describe.
Platform health
The component-status model that reports what a chart install actually did.
Storage overview
A worked example of catalogue charts driving an install path end to end.
Celum AI uses the same three reads:
search_helm_charts to find a chart, get_chart_versions for a platform component’s available versions with the pinned default marked, and get_chart_mirror_status when a version list is empty or an install cannot pull.