API reference

A small, pragmatic surface. The management endpoints below sit next to the Galaxy V1 & V3 serving endpoints on the same TCP tree, so one instance is both control plane and one of the best-behaved Galaxy mirrors your playbooks have talked to.

Serving endpoints (the Galaxy half)

GET/api/v1/roles/ · /api/v1/collections/
Galaxy V1 API — the surface ansible-galaxy talks to. No client changes needed.
GET/api/v3/
Galaxy V3 API — collection indexes and artifact downloads, as served by Galaxy.

Point your clients here and requirement installs resolve against the mirror. Theansible.cfg below is the entire client story:

CLIENTansible.cfgini

[galaxy]
server_list = orbitron

[galaxy_server.orbitron]
url = https://orbitron.internal/api/
# token = YOUR_ORBITRON_TOKEN  # if require_auth_pull is enabled

Management endpoints

GET/healthz
Unauthenticated liveness — 200 when the storage path is writable, 503 when degraded.
POST/api/v1/requirements/roles · /collections
Ingest role & collection YAML manifests. Content-addressed by SHA-256, mirrored by parallel workers.
POSTGET/api/v1/sync · /sync/status
Re-run every stored manifest, or poll progress and a bounded history of finished syncs.
GET/api/v1/manifests
Lists every stored requirements manifest, grouped by type, with the content sha256 used for idempotent ingestion.
GETDELETE/api/v1/storage
Full cached-version inventory. DELETE /storage/{type}/{name}/{version} purges a single cached version.
POST/api/v1/prune
Access-based cleanup with retention window — preview with {"dry_run": true}, nothing is deleted.
GETPOSTDELETE/api/v1/tokens
Token lifecycle: create, list, revoke and rotate admin tokens, with optional per-token TTLs.
GET/api/v1/dump
Streams the entire cache as a gzip tar archive, with a per-file SHA-256 manifest. Never includes the token store.
GET/metrics
Prometheus exposition — uptime, cache counts, version totals and storage bytes.

Every endpoint above except /healthz requires a Bearer token or HTTP Basic auth.

Examples

HEALTHcurlbash

curl -i http://127.0.0.1:8080/healthz
HTTP/1.1 200 OK

MANIFESTScurlbash

curl http://127.0.0.1:8080/api/v1/manifests \
  -H "Authorization: Bearer $ORBITRON_TOKEN"
{
  "roles": [{"file": "roles_x_requirements.yml", "sha256": "737690a6..."}],
  "collections": []
}

INVENTORYcurlbash

curl http://127.0.0.1:8080/api/v1/storage \
  -H "Authorization: Bearer $ORBITRON_TOKEN"
{
  "roles": [
    {"type": "role", "name": "geerlingguy.nginx",
     "versions": [{"version": "1.2.3", "declared": true, "size_bytes": 20480}]}
  ],
  "collections": []
}

PRUNE PREVIEWcurlbash

curl -X POST http://127.0.0.1:8080/api/v1/prune \
  -H "Authorization: Bearer $ORBITRON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true, "days": 90}'
{
  "items": ["/var/lib/orbitron/storage/roles/geerlingguy.nginx/2.0.1"],
  "freed_bytes": 40960,
  "executed": false
}

DUMPcurlbash

curl http://127.0.0.1:8080/api/v1/dump \
  -H "Authorization: Bearer $ORBITRON_TOKEN" \
  -o orbitron-backup.tar.gz

# ?compress=fast trades compression ratio for CPU time
tar -xzf orbitron-backup.tar.gz -C /var/lib/orbitron/storage --strip-components=1

Backing up a whole mirror

/api/v1/dump is the one call for an offline backup. It walks the whole storage directory and streams a gzip tar archive rooted at orbitron/ — every role directory, every collection .tar.gz, git-sourced collection checkouts, the stored requirements manifests and the access index.

orbitron/dump.json
Written as the last entry. Carries the daemon version, a UTC timestamp, the cache inventory, the excluded paths and a SHA-256 per file. Its absence is the signal that a transfer was cut short.
never included
The token store — both the configured tokens_file when it lives inside the storage path and <storage>/tokens.json — plus temp files and anything that is not a regular file. A content backup never carries credentials into an offline vault.
X-Orbitron-Dump-Sync
running or idle at request time. No snapshot lock is taken, so dumping during a sync yields a consistent set of files but not a globally consistent one; the per-file checksums make a torn dump detectable.

There is no Content-Length — a backup job cannot resume a half-finished download. Every valid token may dump: treat a token as read access to the whole cache.

The same thing from Ansible, where the archive is streamed to the controller and verified:

ANSIBLEbackup.ymlyaml

- name: Back up the Orbitron cache
  chrisvanmeer.orbitron.orbitron_dump:
    url: http://127.0.0.1:8080
    token: "{{ vault_orbitron_admin_token }}"
    dest: /var/backups/orbitron/nightly.tar.gz
    read_timeout: 1800
  register: dump