API Reference

Dodil Registry exposes two HTTP surfaces on one host — nothing else. No gRPC, no SDK.

• Docker Registry v2 — /v2/.... The standard OCI distribution protocol: manifests, blobs, uploads, tag listing. You almost never call it by hand; docker, podman, oras, and buildkit speak it for you.
• Control plane — /<org>/.... Plain REST for everything around the images: repositories, artifacts, tags, vulnerability reports, visibility.

Docker v2 compatibility

Registry implements the Docker Registry HTTP API v2 (the OCI distribution spec). Any OCI-compliant client works unmodified — repository names on the wire are <org>/<repo>, so an image reference is:

registry.dodil.io/<org>/<repo>:<tag>

Repositories are created implicitly by the first push; there is no create endpoint on either plane.

Auth

Both planes accept the same two credentials:

# 1. dk_ API key — Basic auth; username can be anything
curl -u "ci:dk_..." https://registry.dodil.io/acme
 
# 2. Bearer JWT (interactive session token)
curl -H "Authorization: Bearer $DODIL_TOKEN" https://registry.dodil.io/acme

Issue keys with dodil auth apikey issue --role registry.developer --service registry — the secret is shown once. docker login is Basic auth under the hood, so the same key drives docker clients, CI, and raw curl.

Public repositories allow anonymous pulls on the v2 plane; everything else requires credentials.

Control-plane conventions

• Responses are raw JSON — no {status, data} envelope. Errors return a non-2xx status with a plain-text or JSON body.

• Field names are snake_case: artifact_count, push_time, scan_overview, fix_version.

• Pagination — list endpoints take page (1-based) and page_size query params and return:

  { "items": [ ... ], "total_count": 42 }

• References — endpoints addressing one artifact take a {reference} path segment that is a tag or a digest (URL-encode digests: sha256%3A...).

• Org is name-keyed — {org} in every path is your organization name, matching the image path.

Health

GET /health

{ "status": "ok", "service": "registry" }

See also

• Core Concepts — why two planes
• CLI Guide — the same surface from dodil registry