NEBULA-API(1)
Nebula Manual
NAMEregistry api — The registry API exposes protocol resources for galaxies, blobs, snapshots, proposals, projections, and schema discovery.
SOURCEnebula/docs/production-registry.md
STATUSpre-alpha · protocol in design
01
Base URL structure
Registry URLs encode the repository identifier. The format supports both direct IDs and named galaxies.
output
https://registry.example.com/repo_abc123.neb
https://registry.example.com/owner/galaxy-name.neb02
Discovery endpoints
The registry exposes protocol and schema discovery for programmatic clients.
output
GET /v1/protocol # Protocol version and capabilities
GET /v1/schema # JSON schema for resources03
Health endpoints
Check registry health and readiness before operations.
output
GET /health/live # Process liveness
GET /health/ready # Dependency readiness (Postgres, S3, etc.)04
Runtime modes
The registry supports different storage backends and auth configurations.
output
# Development: file-backed (local only)
NEBULA_REGISTRY_DEV_MODE=1
NEBULA_REGISTRY_BACKEND=file
# Production: Postgres + object storage
NEBULA_REGISTRY_BACKEND=postgres-object-store
DATABASE_URL=postgres://user:pass@host:5432/nebula
BLOB_STORE_URL=s3://bucket/prefix
NEBULA_AUTH_REQUIRED=true
NEBULA_AUTH_PROVIDER=better-auth-rs
NEBULA_AUTH_BASE_URL=https://auth.example.com
NEBULA_AUTH_SECRET=<32+ byte secret>05
Auth integration
Better Auth RS is mounted at /auth and owns user management, sessions, and API key lifecycle. Nebula translates verified sessions into actors and scopes for authorization.
- →/auth/get-session - Session verification
- →/auth/api-key/create - API key creation
- →/auth/api-key/list - API key listing
- →/auth/api-key/verify - API key verification
06
Admin API
An internal admin API (at /admin/v1) exposes operational endpoints for registry operators.
output
# Enable admin API
NEBULA_ADMIN_API_ENABLED=true
NEBULA_ADMIN_BOOTSTRAP_USER_IDS=user1,user2
# Or by email:
NEBULA_ADMIN_BOOTSTRAP_EMAILS=admin@example.com