Skip to main content

🌙 LunarBit API Gateway

Enterprise-grade API Gateway and AI Proxy System for Lunarbit Studios services.

Version: 2.0.0
Base URL: https://api.lunarbit.dev/
Status: Production
Last Updated: February 7, 2026
Compliance: LunarCore Spec v1 ✅

What's New in v2.0.0

This major update brings enterprise-grade features:

  • 🤖 Multi-provider AI Gateway with intelligent routing
  • 🔐 Advanced API key management with granular permissions
  • 🏗️ Clean architecture with full LunarCore compliance
  • 📊 Structured logging and comprehensive error handling
  • 🚀 Enhanced security and deployment options

Overview​

The LunarBit API Gateway provides production-grade access to project metadata, version management, AI capabilities, and automated update checking for all LunarBit projects. Built with clean architecture principles and full LunarCore compliance, this RESTful API enables developers to integrate sophisticated version management and AI-powered features into their applications.

Key Features​

  • AI Gateway & Proxy - Multi-provider AI support with intelligent routing and automatic failover
  • Version Management - Hierarchical project → channel → version → build architecture
  • Auto-Updates - Safe update system with breaking change detection and compatibility checking
  • Build Verification - Automatic health checks and checksum validation
  • Advanced Authentication - Granular API key permissions with usage tracking
  • Enterprise Security - Rate limiting, CORS protection, and OWASP-compliant headers
  • GitHub Integration - Automatic synchronization with GitHub releases

LunarCore Compliance​

This API fully implements the LunarCore Specification v1.0.0:

  • ✅ LC-VER: Semantic versioning with VERSION constant exposed
  • ✅ LC-LOG: Structured JSON logging with sensitive data redaction
  • ✅ LC-CFG: Environment-based configuration with sensible defaults
  • ✅ LC-ERR: Consistent error hierarchy with LC_ERR_* error codes
  • ✅ LC-SEC: Security-first defaults (HTTPS, API keys, rate limiting)
  • ✅ LC-NAM: Consistent naming conventions (camelCase, PascalCase, etc.)

Architecture​

Clean Architecture Overview​

The API follows clean architecture principles with clear separation of concerns:

┌─────────────────────────────────────────────────────────────┐
│                     Lunarbit API Gateway                     │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Routes    │→ │  Middleware  │→ │ Controllers  │      │
│  └─────────────┘  └──────────────┘  └──────────────┘      │
│         │                                     │              │
│  ┌──────┴─────────────────────────────────────┴────────┐  │
│  │               Services Layer                         │  │
│  │  ProjectService │ AIService │ AuthService           │  │
│  └───────────────────────────────────────────────────────┘  │
│         │                 │                 │                │
│  ┌──────┴────────┐  ┌────┴────────┐  ┌────┴────────┐      │
│  │  GitHub API   │  │ AI Providers│  │   Storage   │      │
│  └───────────────┘  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────────────────────────┘

Layer Structure:

  • API Layer: HTTP routes, controllers, middleware, input validation
  • Core Layer: Business logic services, external provider integrations, data access
  • Infrastructure Layer: Database connections, caching, structured logging, metrics
  • Shared Layer: Custom error classes, application constants, TypeScript types, utilities

AI Provider Architecture​

┌────────────────────────────────────────────────────┐
│           Model Router (✅ Implemented)            │
│  • Priority-based routing                          │
│  • Round-robin load balancing                      │
│  • Least-loaded selection                          │
│  • Fastest provider selection                      │
│  • Automatic failover                              │
└────────────────┬───────────────────────────────────┘
       ┌─────────┴─────────┬──────────┬────────────┐
       │                   │          │            │
┌──────┴───────┐  ┌───────┴──────┐  ┌┴────────┐  ┌┴───────┐
│  LM Studio   │  │   OpenAI     │  │Anthropic│  │ Custom │
│  (✅ Done)   │  │  (✅ Done)   │  │(Design) │  │(Ready) │
└──────────────┘  └──────────────┘  └─────────┘  └────────┘

Getting Started​

Authentication​

To use the API, you'll need an API key. Request one by contacting us at api@lunarbit.dev or through our Discord server.

Include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

Quick Example​

# Check API status
curl https://api.lunarbit.dev/health

# List available projects (requires auth)
curl -H "Authorization: Bearer YOUR_KEY" \
  https://api.lunarbit.dev/projects

# Check AI provider status (no auth required)
curl https://api.lunarbit.dev/ai/status

# Chat with AI (requires auth)
curl -X POST https://api.lunarbit.dev/ai/chat \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Explain semantic versioning"}]}'

AI Capabilities​

Supported Providers​

ProviderStatusFeatures
LM Studio✅ ProductionLocal models, streaming, no costs
OpenAI✅ ProductionGPT-3.5/4, accurate tokens, streaming
Anthropic🔄 DesignedClaude models, ready to implement
Azure OpenAI🔄 DesignedEnterprise OpenAI access
Custom✅ ReadyImplement AIProvider interface

AI Endpoints​

AI Status​

Check available AI providers and models.

Endpoint: GET /ai/status
Authentication: None required

Response:

{
  "enabled": true,
  "providers": [
    {
      "name": "lmstudio",
      "available": true,
      "models": ["llama-3.1-8b-instruct"]
    },
    {
      "name": "openai",
      "available": true,
      "models": ["gpt-4", "gpt-3.5-turbo"]
    }
  ]
}

Chat Completion​

Send messages and get AI responses with streaming support.

Endpoint: POST /ai/chat
Authentication: Required

Request Body:

{
  "messages": [
    {"role": "user", "content": "Explain semantic versioning"}
  ],
  "temperature": 0.7,
  "max_tokens": 500,
  "stream": false,
  "model": "gpt-4"
}

Parameters:

  • messages (required): Array of message objects with role and content
  • temperature (optional, 0-2, default 0.7): Response randomness
  • max_tokens (optional, default 2000): Maximum response length
  • stream (optional, boolean): Enable streaming responses
  • model (optional): Specific model to use

Response:

{
  "response": "Semantic versioning (SemVer) is a versioning scheme...",
  "model": "gpt-4",
  "tokens_used": 156,
  "processing_time_ms": 1247
}

Analyze Changelog​

AI-powered changelog analysis and summarization.

Endpoint: POST /ai/analyze-changelog
Authentication: Required

Request Body:

{
  "version": "1.2.0",
  "changelog": "- Fixed memory leak\n- Added dark mode\n- Breaking: Removed Node 14 support"
}

Response:

{
  "version": "1.2.0",
  "analysis": "This update fixes a memory leak, adds dark mode, and drops Node.js 14 (requires Node 16+).",
  "breaking": true,
  "severity": "major"
}

Model Routing Strategies​

The AI gateway supports multiple routing strategies:

  • Priority: Use providers in order (fallback on failure)
  • Round-Robin: Distribute requests evenly across providers
  • Least-Loaded: Route to provider with fewest active requests
  • Fastest: Route to provider with best average latency

API Key Management​

The API features an advanced key management system with granular permissions and usage tracking.

Permission System​

API keys can have granular permissions:

PermissionAccess
canReadProjectsGET /projects, GET /projects/:id
canReadVersionsGET /projects/:id/channels/:channel/latest
canCheckUpdatesPOST /update/check
canUseAIPOST /ai/chat, POST /ai/analyze-changelog
canCreateKeysPOST /admin/keys (admin only)
canRevokeKeysDELETE /admin/keys/:name (admin only)

Creating API Keys​

Endpoint: POST /admin/keys
Authentication: Admin key required

Request Body:

{
  "name": "My App Key",
  "description": "API key for my application",
  "permissions": {
    "canReadProjects": true,
    "canReadVersions": true,
    "canCheckUpdates": true,
    "canUseAI": true
  },
  "rateLimit": 1000,
  "expiresIn": "90d",
  "allowedProjects": ["trackly"],
  "tags": ["mobile-app", "production"]
}

Response:

{
  "message": "API key created successfully",
  "key": "lbapi_a1b2c3d4e5f6...",
  "name": "My App Key",
  "permissions": {...},
  "createdAt": "2026-02-07T10:00:00Z",
  "expiresAt": "2026-05-08T10:00:00Z",
  "warning": "Save this key now - it will not be shown again!"
}

Key Features​

  • Automatic Expiration: Set expiresIn when creating keys (e.g., "30d", "90d")
  • Rate Limiting: Custom limits per key
  • Usage Tracking: Monitor requests, tokens, errors
  • Project Restrictions: Limit access to specific projects
  • Instant Revocation: Immediately disable compromised keys
  • Tagging: Organize keys with custom tags
  • Key Prefix: All keys use lbapi_ prefix for easy identification

Managing Keys​

List API Keys​

Endpoint: GET /admin/keys
Authentication: Admin key required

Returns all API keys with masked values for security.

Revoke API Key​

Endpoint: DELETE /admin/keys/:keyName
Authentication: Admin key required

Immediately revokes a specific API key.

Key Statistics​

Endpoint: GET /admin/keys/stats
Authentication: Admin key required

Get usage statistics for all API keys.

Authentication​

All API endpoints require authentication via Bearer token in the Authorization header:

Authorization: Bearer your_api_key_here

Rate Limits​

To ensure fair usage and API availability, we enforce multiple types of rate limits:

TypeLimitWindow
Per API Key1,000 requests15 minutes
Per IP Address1,000 requests15 minutes
AI Endpoints100 requests1 hour
Unauthenticated60 requests1 hour

Custom Limits: API keys can have custom rate limits configured when created.

Rate limit status is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1640995200

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff and respect the rate limits.

Error Handling​

All errors follow a consistent format:

{
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "Project 'nonexistent' not found",
    "details": {
      "project": "nonexistent",
      "available_projects": ["trackly", "csviewer"]
    },
    "documentation_url": "https://docs.lunarbit.dev/api-errors#PROJECT_NOT_FOUND",
    "request_id": "req_abc123xyz"
  }
}

Common Error Codes​

CodeStatusDescription
INVALID_REQUEST400Malformed request body or parameters
UNAUTHORIZED401Missing or invalid authentication
FORBIDDEN403Insufficient permissions for operation
NOT_FOUND404Resource does not exist
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server-side error occurred

Endpoints​

Health Check​

Check API availability and response time.

Endpoint: GET /health
Authentication: None required

Response:

{
  "status": "healthy",
  "timestamp": "2026-02-07T12:00:00Z",
  "version": "2.0.0"
}

Projects​

List All Projects​

Get all available LunarBit projects.

Endpoint: GET /projects
Authentication: Required

Response:

{
  "projects": [
    {
      "id": "trackly",
      "name": "Trackly",
      "description": "Business asset management system",
      "repository": "LunarBit-dev/Trackly",
      "channels": ["stable", "beta"],
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2026-02-07T08:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Get Project Details​

Retrieve detailed information about a specific project.

Endpoint: GET /projects/{projectId}
Authentication: Required

Path Parameters:

ParameterTypeDescription
projectIdstringUnique project identifier

Response:

{
  "id": "trackly",
  "name": "Trackly",
  "description": "Business asset management system with license tracking",
  "repository": "LunarBit-dev/Trackly",
  "homepage": "https://trackly.lunarbit.dev",
  "channels": [
    {
      "id": "stable",
      "name": "Stable",
      "description": "Production-ready releases",
      "auto_update": true
    },
    {
      "id": "beta",
      "name": "Beta",
      "description": "Preview releases for testing",
      "auto_update": false
    }
  ],
  "latest_version": "1.2.5",
  "total_downloads": 12847,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2026-02-07T08:30:00Z"
}

Versions​

List Project Versions​

Get all versions for a project in a specific channel.

Endpoint: GET /projects/{projectId}/channels/{channelId}/versions
Authentication: Required

Path Parameters:

ParameterTypeDescription
projectIdstringUnique project identifier
channelIdstringRelease channel (stable, beta, dev)

Query Parameters:

ParameterTypeDefaultDescription
pageinteger1Page number
per_pageinteger20Results per page (max 100)
sortstringdescSort order (asc or desc)

Response:

{
  "versions": [
    {
      "id": "1.2.5",
      "name": "v1.2.5",
      "description": "Bug fixes and performance improvements",
      "release_notes": "## Changes\n- Fixed dashboard loading issue\n- Improved query performance",
      "breaking_changes": false,
      "published_at": "2026-02-05T14:30:00Z",
      "downloads": 3421,
      "build_count": 2
    }
  ],
  "total": 15,
  "page": 1,
  "per_page": 20
}

Get Version Details​

Retrieve detailed information about a specific version.

Endpoint: GET /projects/{projectId}/channels/{channelId}/versions/{versionId}
Authentication: Required

Response:

{
  "id": "1.2.5",
  "name": "v1.2.5",
  "description": "Bug fixes and performance improvements",
  "release_notes": "## Changes\n- Fixed dashboard loading issue\n- Improved query performance\n- Updated dependencies",
  "breaking_changes": false,
  "published_at": "2026-02-05T14:30:00Z",
  "downloads": 3421,
  "builds": [
    {
      "id": "windows-x64",
      "platform": "windows",
      "architecture": "x64",
      "file_size": 125829120,
      "download_url": "https://cdn.lunarbit.dev/trackly/1.2.5/trackly-1.2.5-win-x64.exe",
      "checksum": {
        "sha256": "abc123...",
        "md5": "def456..."
      }
    }
  ]
}

Builds​

Get Build Information​

Retrieve information about a specific build.

Endpoint: GET /projects/{projectId}/channels/{channelId}/versions/{versionId}/builds/{buildId}
Authentication: Required

Response:

{
  "id": "windows-x64",
  "version": "1.2.5",
  "platform": "windows",
  "architecture": "x64",
  "file_name": "trackly-1.2.5-win-x64.exe",
  "file_size": 125829120,
  "download_url": "https://cdn.lunarbit.dev/trackly/1.2.5/trackly-1.2.5-win-x64.exe",
  "checksum": {
    "sha256": "abc123def456...",
    "md5": "def456abc123..."
  },
  "created_at": "2026-02-05T14:30:00Z",
  "downloads": 1847,
  "status": "verified"
}

Download Build​

Download a specific build artifact.

Endpoint: GET /projects/{projectId}/channels/{channelId}/versions/{versionId}/builds/{buildId}/download
Authentication: Required

Response: Redirects to CDN download URL

Updates​

Check for Updates​

Check if updates are available for a specific version.

Endpoint: GET /projects/{projectId}/channels/{channelId}/update
Authentication: Required

Query Parameters:

ParameterTypeRequiredDescription
current_versionstringYesCurrent installed version
platformstringYesTarget platform (windows, macos, linux)
architecturestringYesTarget architecture (x64, arm64)

Response (Update Available):

{
  "update_available": true,
  "current_version": "1.2.3",
  "latest_version": "1.2.5",
  "breaking_changes": false,
  "release_notes": "## Changes\n- Fixed dashboard loading\n- Performance improvements",
  "download_url": "https://cdn.lunarbit.dev/trackly/1.2.5/trackly-1.2.5-win-x64.exe",
  "file_size": 125829120,
  "checksum": {
    "sha256": "abc123...",
    "md5": "def456..."
  },
  "published_at": "2026-02-05T14:30:00Z"
}

Response (No Updates):

{
  "update_available": false,
  "current_version": "1.2.5",
  "latest_version": "1.2.5",
  "message": "You are running the latest version"
}

Launcher Update Check​

Advanced update checking for launcher applications with multiple project support.

Endpoint: POST /update/check
Authentication: Required

Request Body:

{
  "client": {
    "launcher_version": "2.1.0",
    "os": "windows",
    "os_version": "10.0.19045",
    "architecture": "x64"
  },
  "installed": [
    {
      "project_id": "trackly",
      "version": "1.0.0",
      "channel": "stable"
    },
    {
      "project_id": "csviewer",
      "version": "2.3.1",
      "channel": "beta"
    }
  ]
}

Response:

{
  "updates_available": true,
  "launcher_update": {
    "available": false,
    "current": "2.1.0",
    "latest": "2.1.0"
  },
  "project_updates": [
    {
      "project_id": "trackly",
      "update_available": true,
      "current_version": "1.0.0",
      "latest_version": "1.2.5",
      "breaking_changes": true,
      "download_url": "https://cdn.lunarbit.dev/trackly/1.2.5/trackly-1.2.5-win-x64.exe"
    },
    {
      "project_id": "csviewer",
      "update_available": false,
      "current_version": "2.3.1",
      "latest_version": "2.3.1"
    }
  ]
}

Usage Examples​

cURL​

The API is designed to work seamlessly with cURL and any HTTP client. Below are common usage patterns:

# Check API health
curl https://api.lunarbit.dev/health

# List projects (requires authentication)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lunarbit.dev/projects

# Check for updates
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lunarbit.dev/projects/trackly/channels/stable/update?current_version=1.2.3&platform=windows&architecture=x64"

# Chat with AI
curl -X POST https://api.lunarbit.dev/ai/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Explain semantic versioning"}],
    "temperature": 0.7,
    "max_tokens": 500
  }'

# Create API key (admin only)
curl -X POST https://api.lunarbit.dev/admin/keys \
  -H "Authorization: Bearer ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App Key",
    "permissions": {
      "canReadProjects": true,
      "canUseAI": true
    },
    "expiresIn": "90d"
  }'
Client Libraries Coming Soon

Official TypeScript/JavaScript and Python client libraries are planned for future releases. For now, use standard HTTP clients or cURL to interact with the API.

Best Practices​

API Key Security​

  • Store API keys securely in environment variables
  • Never commit API keys to version control
  • Rotate keys regularly for production applications
  • Use separate keys for development and production

Request Optimization​

  • Cache responses when appropriate (versions don't change frequently)
  • Respect rate limits with exponential backoff
  • Use conditional requests with ETag headers
  • Batch requests when possible

Error Handling​

Always handle errors gracefully. Example with bash/curl:

# Function to handle rate limiting with exponential backoff
call_api_with_retry() {
  local url="$1"
  local max_retries=3
  local retry_count=0
  local wait_time=1

  while [ $retry_count -lt $max_retries ]; do
    response=$(curl -s -w "\n%{http_code}" -H "Authorization: Bearer $API_KEY" "$url")
    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | head -n-1)

    if [ "$http_code" -eq 429 ]; then
      echo "Rate limited. Waiting ${wait_time}s before retry..."
      sleep $wait_time
      wait_time=$((wait_time * 2))
      retry_count=$((retry_count + 1))
    elif [ "$http_code" -eq 401 ]; then
      echo "Error: Invalid API key"
      exit 1
    elif [ "$http_code" -eq 200 ]; then
      echo "$body"
      return 0
    else
      echo "Error: HTTP $http_code"
      echo "$body"
      exit 1
    fi
  done

  echo "Max retries exceeded"
  exit 1
}

# Usage
call_api_with_retry "https://api.lunarbit.dev/projects"

Response Format​

All successful responses return JSON with appropriate HTTP status codes:

  • 200 OK - Successful GET request
  • 201 Created - Successful POST request
  • 204 No Content - Successful DELETE request
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid API key
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource doesn't exist
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

Security​

Security Features​

The API implements comprehensive security measures:

  • ✅ API Key Authentication - Granular permission-based access control
  • ✅ Rate Limiting - IP and key-based limits to prevent abuse
  • ✅ CORS Protection - Configurable origin restrictions
  • ✅ Security Headers - OWASP-recommended headers automatically applied
  • ✅ Input Sanitization - Request validation and sanitization
  • ✅ Request ID Tracking - Full request/response audit trail
  • 🔄 API Key Encryption - Enhanced key storage (planned)
  • 🔄 Audit Logging - Comprehensive usage logging (planned)

Security Headers​

All responses include these security headers:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'

Security Best Practices​

  1. Never commit API keys - Always use environment variables
  2. Rotate keys regularly - Set expiration dates on production keys
  3. Use HTTPS in production - Enable SSL/TLS certificates
  4. Monitor usage - Check /admin/keys/stats regularly
  5. Revoke compromised keys - Immediate revocation available
  6. Limit permissions - Grant minimum required access per key
  7. Enable audit logging - Track all API usage for security review
  8. Rate limit appropriately - Configure limits based on usage patterns

Deployment​

Environment Variables​

Required:

NODE_ENV=production
PORT=3000
API_KEY_ADMIN=your_admin_key_here

Optional:

# GitHub Integration
GITHUB_TOKEN=ghp_your_token

# AI Providers
LMSTUDIO_ENABLED=true
LMSTUDIO_BASE_URL=http://localhost:1234
OPENAI_API_KEY=sk-...
OPENAI_ENABLED=true

# Caching
CACHE_TTL=300000

# Logging
LOG_LEVEL=info
LOG_FORMAT=json

Deployment Options​

Option 1: Traditional Server (Debian/Ubuntu)​

The API includes an automated deployment script for Debian/Ubuntu systems:

# Transfer files to server
rsync -avz --exclude 'node_modules' ./api/ user@server:/home/user/api/

# Run deployment script
ssh user@server
cd ~/api
chmod +x deploy-debian.sh
./deploy-debian.sh

The script automatically:

  • Installs Node.js 20.x
  • Installs dependencies
  • Builds TypeScript
  • Configures systemd service
  • Starts the API

Option 2: Cloudflare Workers​

# Set secrets
wrangler secret put GITHUB_TOKEN
wrangler secret put API_KEY_READ
wrangler secret put API_KEY_ADMIN

# Deploy
npm run deploy

Option 3: Docker​

# Build image
docker build -t lunarbit-api .

# Run container
docker run -d \
  -p 3000:3000 \
  -e API_KEY_ADMIN=your_admin_key \
  --name lunarbit-api \
  lunarbit-api

Service Management (systemd)​

# Start service
sudo systemctl start lunarbit-api

# Stop service
sudo systemctl stop lunarbit-api

# Restart service
sudo systemctl restart lunarbit-api

# View logs
sudo journalctl -u lunarbit-api -f

# Check status
sudo systemctl status lunarbit-api

Changelog​

Version 2.0.0 (Current - February 2026)​

Major Features:

  • ✅ LunarCore Compliance - Full implementation of LunarCore Specification v1.0.0
  • ✅ Clean Architecture - Comprehensive restructuring with layer separation
  • ✅ AI Gateway & Proxy - Multi-provider support (LM Studio, OpenAI, Anthropic)
  • ✅ Advanced Model Router - 4 routing strategies with automatic failover
  • ✅ Granular API Key Management - Permission-based access control with usage tracking
  • ✅ Structured Logging - JSON output with sensitive data redaction
  • ✅ Enhanced Error Handling - 15+ custom error classes with detailed context
  • ✅ Launcher Update System - Advanced multi-project update checking
  • ✅ Security Enhancements - OWASP-compliant headers, rate limiting, CORS
  • ✅ Build Verification - Automatic health checks and checksum validation
  • ✅ GitHub Integration - Automatic synchronization with GitHub releases

AI Capabilities:

  • Chat completion with streaming support
  • Changelog analysis and summarization
  • Multiple provider support with intelligent routing
  • Token tracking and optimization

Breaking Changes from v1:

  • Authentication header format changed (Bearer instead of ApiKey)
  • Base URL includes /api/v2 path
  • Error response format restructured with detailed codes
  • API keys from v1 are not compatible with v2

Version 1.0.0 (June 2025)​

  • Initial public release
  • Basic version management and update checking
  • GitHub integration for project data
  • Simple API key authentication

Migration from v1.0.0​

If you're using API v1, migrate to v2 with these changes:

Base URL

- https://api.lunarbit.dev/api/v1
+ https://api.lunarbit.dev/api/v2

Authentication Header

- Authorization: ApiKey your_key
+ Authorization: Bearer your_key

Error Response Format

v2 provides more detailed error information:

// v2 error format
{
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "Project 'xyz' not found",
    "documentation_url": "https://docs.lunarbit.dev/api-errors#PROJECT_NOT_FOUND"
  }
}

Note: v1 API keys are not compatible with v2. Request new API keys for v2 access.

Development​

Project Structure​

api/
├── src/
│   ├── api/v2/              # API routes and controllers
│   ├── core/                # Business logic
│   │   ├── providers/ai/    # ✅ AI provider implementations
│   │   ├── services/        # Business services
│   │   └── repositories/    # Data access
│   ├── infrastructure/      # Infrastructure concerns
│   │   └── logging/         # ✅ Structured logging
│   ├── shared/              # Shared utilities
│   │   ├── errors/          # ✅ Custom error classes
│   │   └── constants/       # ✅ Application constants
│   ├── keymanager.ts        # API key management
│   ├── lmstudio.ts          # LM Studio integration
│   ├── security.ts          # Security middleware
│   ├── types.ts             # TypeScript types
│   └── utils.ts             # Utility functions
├── data/
│   └── api-keys.json        # API key storage
├── server.ts                # Main server file
├── openapi.yaml             # OpenAPI specification
└── README.md                # Documentation

Available Scripts​

# Development
npm run dev          # Start with hot reload
npm run dev:watch    # Start with file watching

# Production
npm run build        # Compile TypeScript
npm start            # Start production server

# Deployment
npm run deploy       # Deploy to Cloudflare Workers

# Code Quality
npm run lint         # Run ESLint
npm run format       # Format code with Prettier
npm test             # Run tests

Adding a Custom AI Provider​

The API supports custom AI providers through a standardized interface:

// Implement the AIProvider interface
import { AIProvider, CompletionRequest, CompletionResponse } from './src/core/providers/ai/BaseProvider';

export class CustomProvider implements AIProvider {
  async chatCompletion(request: CompletionRequest): Promise<CompletionResponse> {
    // Your implementation
  }

  async *streamCompletion(request: CompletionRequest): AsyncIterable<string> {
    // Streaming implementation
  }

  async isHealthy(): Promise<boolean> {
    // Health check
  }

  async getModels(): Promise<string[]> {
    // List available models
  }
}

// Register with ModelRouter
const customProvider = new CustomProvider(config);
modelRouter.registerProvider('custom', customProvider);

Implementation Status​

✅ Completed (Phase 1):

  • Architecture audit and clean architecture setup
  • AI provider system with routing strategies
  • Error handling system (15+ custom errors)
  • Structured logging infrastructure
  • Application constants (100+ centralized)

🚧 In Progress (Phase 2):

  • Service layer implementation
  • Repository layer abstraction
  • Controller refactoring
  • Enhanced input validation

📋 Planned (Phase 3):

  • Multi-tenancy support
  • Enhanced security features
  • Metrics collection
  • Database integration
  • Caching layer
  • CI/CD pipelines

Support and Resources​

Documentation​

  • API Documentation: docs.lunarbit.dev
  • OpenAPI Specification: Available at openapi.yaml in the API repository
  • Interactive API Docs: Available at /docs endpoint (when deployed)
  • GitHub Repository: github.com/LunarBit-dev/api

Get Help​

Need assistance with the API? Multiple support channels available:

Additional Resources​

  • LunarCore Specification: github.com/LunarBit-dev/LunarCore-spec
  • Example Scripts: cURL examples and integration patterns in the API repository
  • Client Libraries: TypeScript and Python SDKs planned for future release

Terms and Policies​

  • API usage is subject to our Terms of Service
  • Review our Privacy Policy for data handling
  • Rate limits may be adjusted to ensure service quality
  • API availability target: 99.9% uptime

License​

The LunarBit API is proprietary software.

Questions? Contact us at api@lunarbit.dev or join our Discord community.