Chicorée REST API

This API follows the registry's features: whenever a feature is added, changed or removed, the endpoints that expose it and this documentation change with it in the same release. The revision moves every time — compare it with the changelog before relying on a new field, and read the changelog before upgrading.

Current revision: 2026-09-22.1 · Changelog · index: GET https://chicor.ee/api/v1

Everything the web app can do with organizations, repositories, tags and images is available as JSON under /api/v1. The same personal access tokens that authenticate docker login authenticate the API, with the same roles and restrictions, so a token that can push an image can read its scan result, and one limited to a repository sees nothing else.

Authentication

Send the credential in the Authorization header:

export TOKEN=chc_pat_…
curl -H "Authorization: Bearer $TOKEN" https://chicor.ee/api/v1/me
# Basic auth works too — the token is the password, the user name is ignored:
curl -u "me:$TOKEN" https://chicor.ee/api/v1/me

Expired tokens, banned accounts and unknown secrets answer 401; a valid credential without the right answers 403 with the reason. Every use of a token updates its last used time and address (Settings → Access tokens).

Keyless CI authentication

A CI job does not need a stored secret. An organization trusts the workflow's identity once (Organization → Service accounts → CI identities, or the /orgs/{org}/ci-identities endpoints): the issuer of its OIDC tokens and the subject they carry, exact or with * wildcards, plus a permission and an optional repository list. The job then exchanges the token it gets from its CI system for a registry credential:

# GitHub Actions (permissions: id-token: write); the audience is this registry's URL
OIDC=$(curl -sS -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
  "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://chicor.ee" | jq -r .value)
curl -sS -H "Content-Type: application/json" -d "{"token": "$OIDC"}" https://chicor.ee/api/v1/auth/exchange
# → { "token": "chc_ci_…", "expiresAt": "…", "dockerLogin": { "registry": "chicor.ee", "username": "ci", "password": "chc_ci_…" } }

The exchange verifies the token against the issuer's published keys (only issuers some organization trusts are contacted), checks that the audience is https://chicor.ee or chicor.ee, and matches the subject; GitHub subjects look like repo:owner/repo:ref:refs/heads/main (the token itself carries ids, repo:owner@123/repo@456:ref:…; both spellings match), GitLab's like project_path:group/project:ref_type:branch:ref:main. The credential is a signed token with no stored state: deleting the identity revokes it at once. The .github/actions/login action in the repository does all of this and runs docker login; .github/actions/build-push (build, push with SBOM and provenance, sign, attest) and the reusable release-images.yml workflow build on it — see the README's GitHub Actions section.

Administrators can switch the whole API off (Administration → Auth providers → Access, default from API_ENABLED): every endpoint, the index and the OpenAPI document then answer 403 with code api_disabled. docker login and the jobs API are not affected.

Conventions

• Responses are JSON (application/json, UTF-8). Timestamps are ISO 8601 in UTC (2026-09-05T08:41:12.000Z), sizes are bytes, digests are sha256:<64 hex>. Absent values are null, not omitted.
• Requests with a body send JSON with Content-Type: application/json.
• Paging. Lists take page (from 1) and per_page (1–100, default 50) and answer { "items": [...], "page": 1, "perPage": 50, "total": 123, "pages": 3 }. A page past the end returns the last page.
• Booleans in the query string are true/1/yes (anything else is false).
• Repository names of proxy caches can be nested (bitnami/redis); in a path they are one segment with the slash percent-encoded: /repos/dockerhub/bitnami%2Fredis. Top-level images (chicor.ee/nginx) live in the library organization.
• Renamed or transferred repositories are not redirected by the API; use the new name (docker pull and the web pages do redirect).
• Every response carries X-Api-Version: 1 and X-Api-Revision: 2026-09-22.1, and Cache-Control: private, no-store.
• Changes made through the API are audited like changes made in the app, with "via": "api" in the entry's details.
• Unknown paths under /api/v1 answer a JSON 404; an unsupported method answers 405.
• Conditional requests. Every successful GET carries a weak ETag; send it back as If-None-Match and an unchanged answer comes back as 304 without a body (the rate-limit and deprecation headers still apply).
• Exports. GET …/manifests/{digest}/vulnerabilities?format=sarif is the image's scan as SARIF 2.1.0 for GitHub code scanning and security dashboards (accepted risks become suppressions); ?format=vex is a CycloneDX 1.5 VEX document in which accepted risks are not_affected with their justification and everything else is in_triage.
• Rate limits. Requests are counted per credential (per address without one) in fixed windows set by the administrators (Administration → Rate limits, defaults RATE_LIMIT_API_AUTHENTICATED=1200/1m and RATE_LIMIT_API_ANONYMOUS=120/1m; instance administrators are exempt). Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds); over the limit the API answers 429 rate_limited with Retry-After.
• Deprecations. An endpoint that is going away is announced first: its responses carry a Deprecation header (and Sunset once a date is set) with a Link to this documentation, the reference marks it, and it stays for at least one more revision. Watch the changelog for Removed: lines.

Errors

{ "error": "This access token is read-only; delete tags here needs a read & write token.", "code": "forbidden" }

Some errors add a details object (the offending field, or queued: false when a scan was not started).

Tools

• API browser. The Browse & try tab above lists every endpoint with its parameters, sends real requests with your browser session or a token you paste, and shows the curl line for the same call.
• OpenAPI. GET https://chicor.ee/api/v1/openapi.json is an OpenAPI 3.1 document for Swagger UI, Postman, Insomnia or client generators (response schemas are inferred from the examples below).

Changelog

This API follows the registry's features: whenever a feature is added, changed or removed, the endpoints that expose it and this documentation change with it in the same release. The revision moves every time — compare it with the changelog before relying on a new field, and read the changelog before upgrading.

2026-09-22.1

• Service accounts: an account is named by its handle, <organization>/<name> (acme/ci-deploy), wherever it acts or is listed — pushedBy.label, the webhook actor.name, the activity feed, the tag page, the audit log (actor and target labels) and the expiry email — so two organizations' ci accounts are told apart. The service-account responses, DELETE …/service-accounts/{id} and GET /me carry the new handle next to name, which stays the bare name.
• Keyless CI: a trusted identity is named GitHub Actions · <organization>/<identity> in the same places (it read GitHub Actions · <identity> before).

2026-09-09.2

• General: GET / carries build — the release version and short commit the web app was built from (APP_VERSION / APP_COMMIT image build arguments: the release workflow sets them from the tag, scripts/deploy.sh from the checkout); both are null when unknown. The footer of every page shows the same.

2026-09-09.1

• General: GET / features gains mirrorsRequireCredentials — a third mirroring mode, “Own credentials only” (Administration → Auth providers → Access → Features, or MIRRORS_REQUIRE_CREDENTIALS=true): mirroring stays on, but every mirror or import must carry the member's own credentials for the source registry, so its rate limit is theirs rather than the instance's; mirrors without credentials stop syncing until they get some. Proxy caches are unaffected.

2026-09-07.7

• Images and webhooks: a push by a keyless CI identity is named GitHub Actions · <identity> (the issuer's label, then the identity name) in pushedBy.label, in the activity feed and as the webhook actor (type ci); it read CI: <identity> or fell back to deleted service account before.
• General: GET / carries features — whether mirroring / importing and proxy caches are available on this instance (Administration → Auth providers → Access → Features, or MIRRORING_ENABLED / PROXY_CACHES_ENABLED). Off, the import mode, mirror settings and proxy set-up disappear, existing mirrors stop syncing and existing caches fetch nothing new.
• Repositories: pullCount counts image pulls the way Docker Hub does — a GET of an image or index by a client. The registry's own reads, HEAD revalidations, attached artifacts (signatures, attestations, SBOMs) and the platform variant fetched by digest right after its index no longer count, so one docker pull is one pull. Existing counts were recomputed from the event log.

2026-09-07.6

• Artifacts: BuildKit's attestation entries (unknown/unknown index members) come back with format: "in-toto" and no verification — they are unsigned statements, not envelopes; previously they were reported as dsse with invalid: no DSSE envelope payload. Cached classifications are corrected on the next read.

2026-09-07.5

• Security: GET /repos/{org}/{repo}/artifacts/{digest}/packages pages through the packages of an SBOM artifact (q, page, per_page up to 500), sorted by name; the tag page's package dialog uses the same list instead of loading the whole document.
• Keyless CI: GitHub now writes the owner's and the repository's ids into the token subject (repo:owner@123/repo@456:ref:…); POST /auth/exchange matches trusted identities written with or without the ids, so subjects documented as repo:owner/repo:ref:… keep working.

2026-09-07.4

• Tags: sizeBytes and layerCount of a multi-arch tag are those of its first platform variant the registry holds (previously null), and the new sizePlatform names that platform (linux/amd64); it is null for single-platform images. The tag list and the untagged list on the repository page show the same figures.
• Repositories: kind is judged from that variant when the newest tag is a multi-arch index, so an image pushed for several platforms is image (previously empty).

2026-09-07.3

• Helm charts: GET /repos/{org}/{repo}/tags/{tag}/chart carries provenance when the chart was pushed with its .prov file (which files it names, whether the archive matches, the PGP key id). Tag and manifest details treat a manifest as a chart by its config media type even when Chart.yaml cannot be read.

2026-09-07.2

• Helm charts: repositories carry kind (image | chart | empty, from the newest tag) and helmReference (oci://…) for charts; tags carry chart: { name, version, appVersion }; manifest and tag details carry kind, chart (Chart.yaml) and helm commands. New GET /repos/{org}/{repo}/tags/{tag}/chart returns Chart.yaml, values.yaml, the README and the file list from the archive. For charts, platform, config and scan are null in tag and manifest details.

2026-09-07.1

• Teams: GET/POST /orgs/{org}/teams, GET/PATCH/DELETE /orgs/{org}/teams/{team}, GET /orgs/{org}/teams/{team}/members, PUT/DELETE /orgs/{org}/teams/{team}/members/{userId}. Teams group members of an organization so repository access can be granted to all of them at once.
• Per-repository permissions: GET /repos/{org}/{repo}/access, PUT/DELETE /repos/{org}/{repo}/access/{user|team}/{id} with permission: pull | push | admin. The organization role stays the baseline for every repository; a grant raises what one person or one team may do in one repository. Docker tokens, the API's write checks and the pages honour grants.
• GET /repos/{org}/{repo}/size-history?days= — the compressed size of the newest image pushed each day; the repository page charts it for members.
• Notation signatures: referrers of type application/vnd.cncf.notary.signature are recognised (format: notation in attestation and signature responses), their JWS envelope verified against the embedded certificate, and counted as verified when the signing certificate or its issuer is in the trust store — trusted signing keys now accept X.509 certificate PEMs.

2026-09-06.9

• Webhook format custom with payloadTemplate: a JSON body of your own with {{placeholders}} (repository, organization, tag, digest, reference, registry, actor, timestamp, deliveryId, event.); a value that is exactly "{{event}}" embeds the whole event. Webhook responses carry payloadTemplate (null for other formats).

2026-09-06.8

• Webhook format none: the delivery is the bare request (method of your choice, headers, authentication) with no body — for deploy hooks that read their parameters from the URL and would misread the payload, such as a PaaS deploy endpoint.

2026-09-06.7

• Webhooks accept method: GET: the delivery carries no body (event and delivery id stay in the headers, authentication applies as before), for receivers that act on the request itself — a deploy hook, say.

2026-09-06.6

• Scan workers: Administration → Scanning → "Offload scans to workers" (SCAN_WORKERS, SCAN_WORKER_TOKEN) hands Trivy scans to external workers over the internal worker protocol (POST /api/internal/worker/claim, /heartbeat, /tasks/<id>/result, /tasks/<id>/fail, bearer token; not part of /api/v1). The worker is a separate program (scan-worker); the protocol is documented in the README. Without a worker online, scans run inline as before. No /api/v1 change.
• TRIVY_SERVER_TOKEN (environment only) authenticates the web container and the bundled trivy server profile to a Trivy server started with --token, so one vulnerability database can serve every replica and every scan worker.

2026-09-06.5

• The Attestations tab shows the cosign/oras sign-and-attach commands only to viewers who may push to the repository (owner, admin or member of a non-proxy organization, instance administrators); everyone else sees a plain note. No API change.

2026-09-06.4

• The library organization is virtual in the UI: no list, search result, dashboard entry, notification, audit label or job result shows a library/ prefix, and /<name> opens the top-level repository. Storage and the /orgs/library/… routes are unchanged; path and reference fields already omitted the prefix.
• Explore opens with an overview — trending repositories (pulls in the last 7 days), organizations busiest first with drill-down, recently updated — and ?view=all is the filterable list. No API change.
• Anonymous calls to the header search typeahead (/api/search) count against the anonymous API rate limit per address (RATE_LIMIT_API_ANONYMOUS).

2026-09-06.3

• Editions: Administration → Branding (INSTANCE_EDITION as default) switches the landing page between self-hosted wording and a hosted service — sign-up as the call to action, the free plan named from the default limits, a link to the account portal's plans. No API change.
• Browsing without an account: Explore, search, organization pages and public repositories open for visitors without a session, in a reduced shell with sign-in and sign-up; pages that need a user still redirect to sign-in. No API change.

2026-09-06.2

• Storage enforcement: the quota-enforce job (Administration → Jobs, POST /api/jobs/quota-enforce) notifies organizations and accounts above their storage limit and, after graceDays, removes the oldest images until the limit is met, protected tags excepted, then runs garbage collection. New notification and organization webhook events quota.exceeded and quota.pruned.

2026-09-06.1

• Changed: the plan card on Settings and Organization → Settings appears only while an account portal is configured; a self-hosted registry with plain limits shows users nothing about them. The label on limits rows is documented accordingly.

2026-09-05.5

• Changed: an organization's own limit governs it alone. When an organization has a storage or repository limit of its own, the owners' account limits are not consulted for it and its usage does not count against their accounts; account limits cover the owner's organizations without such a limit. GET /me/usage and GET /users/{userId}/usage report that pool. Enforced the same way by registryd at push time.
• OpenAPI: integer | null body fields are typed as nullable integers, and enums with null carry a JSON null instead of the string "null".

2026-09-05.4

• Member limit: organizations can be capped at a number of members (Administration → Organizations → Limits, maxMembers); an open invitation holds a seat. Enforced when inviting, accepting an invitation, adding a member and on group-binding logins. GET /orgs/{org}/usage reports members and maxMembers.
• Usage: GET /orgs/{org}/usage and the new GET /me/usage carry the month's traffic (pullBytes, redirectBytes, pushBytes, blobPulls, manifestPulls; ?month=YYYY-MM) and the label administrators gave the limits.
• Administration: GET /users (exact email or search), GET /users/{userId}, GET /users/{userId}/organizations, GET /users/{userId}/usage; GET/PATCH/DELETE /orgs/{org}/limits and /users/{userId}/limits read, change and drop limits rows, including a label shown to the owner and an administrators-only note.
• Default limits: Administration → Limits gives every new account and organization a limits row (DEFAULT_USER_MAX_ORGANIZATIONS, DEFAULT_USER_MAX_PUBLIC_REPOS, DEFAULT_USER_MAX_PRIVATE_REPOS, DEFAULT_USER_MAX_STORAGE_GIB, DEFAULT_ORG_MAX_PUBLIC_REPOS, DEFAULT_ORG_MAX_PRIVATE_REPOS, DEFAULT_ORG_MAX_STORAGE_GIB, DEFAULT_ORG_MAX_MEMBERS as defaults).
• Account portal: Administration → Limits (PORTAL_URL, PORTAL_LABEL as defaults) adds a Manage button to the account and organization settings that opens the portal with a one-time token; the portal verifies it with POST /api/auth/one-time-token/verify.

2026-09-05.3

• Retag: PUT /repos/{org}/{repo}/tags/{tag} points a tag at an image already in the repository.
• Promote: POST …/tags/{tag}/copy and POST …/manifests/{digest}/copy copy an image (with variants and attached artifacts) into another repository, creating it when missing.
• Scan gate: GET …/manifests/{digest}/scan waits for a running scan and judges it against a threshold (wait, fail_on, unrated); POST …/scan accepts the same parameters to queue and wait in one call.
• A composite GitHub Action, .github/actions/scan-gate, fails a job on the gate's verdict.
• Organizations: create, rename and delete; usage against limits; policies (default visibility, pull policy, signature policy, member keys) to read and change.
• Service accounts: list, create (secret returned once), details, delete and rotate.
• Members and invitations: change roles, remove members, list, create and cancel invitations.
• Webhooks: list, create, read, update, delete and test, for organizations and repositories.
• Repository policies: read the effective pull and signature policy, change the overrides.
• Exports: GET …/vulnerabilities?format=sarif (SARIF 2.1.0) and ?format=vex (CycloneDX 1.5 VEX) for security dashboards and GitHub code scanning.
• Conditional requests: GET answers carry a weak ETag and honour If-None-Match with 304.
• The OpenAPI document is validated by npm run lint, and administrators see a notice on the overview when the API revision changed since they last acknowledged it.
• Rate limits: requests are counted per credential (per address anonymously) in windows set under Administration → Rate limits (RATE_LIMIT_API_AUTHENTICATED, RATE_LIMIT_API_ANONYMOUS); over the limit the API answers 429 with the new code rate_limited and Retry-After, and every answer carries X-RateLimit-Limit / -Remaining / -Reset.
• Metrics: chicoree_api_requests_total{endpoint,method,status,credential} on the Prometheus endpoint.
• Deprecation policy: endpoints that are going away carry Deprecation, Sunset and Link headers and are marked in the docs for at least one revision before removal.
• Keyless CI authentication: POST /auth/exchange trades a workflow's OIDC token (GitHub Actions, GitLab, any trusted issuer) for a short-lived chc_ci_ credential that works for the API and docker login; organizations manage the trusted identities under /orgs/{org}/ci-identities and in Organization → Service accounts. A login GitHub Action (.github/actions/login) wraps the exchange.

2026-09-05.2

• Administrators can switch the API off (Administration → Auth providers → Access, default from API_ENABLED); every endpoint then answers 403 with the new error code api_disabled.

2026-09-05.1

• Initial release of the REST API under /api/v1.
• Organizations: list, details, repositories, members and the audit log.
• Repositories: create, read, update and delete; tags; untagged manifests; stars.
• Images: manifest details with config, layers and variants; delete by tag or digest; vulnerabilities; signatures, SBOMs and provenance; queue a scan.
• Search across repositories, tags, digests and organizations.
• Personal access tokens, service accounts and the browser session authenticate; read-only tokens are refused on writes.