ORBITRONGet Started

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/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
}