FreeLLMAPI Premium Live Catalog: Real-Time Model Updates Explained

The Premium Live Catalog is a signed, auto-updating model feed that replaces FreeLLMAPI's static monthly snapshot with fresh free-tier models and updated quota limits every 12 hours, accessible via a $19/year or $49 lifetime license key.

FreeLLMAPI is an open-source LLM gateway that aggregates free-tier models from multiple providers into a unified API. While the free version ships with a static JSON snapshot that updates only with new app releases, the premium live catalog feature in FreeLLMAPI enables automatic synchronization with the upstream catalog service, delivering new models and rate limit adjustments within days of release rather than weeks.

How the Premium Live Catalog Works

License Storage and Authentication

When a user activates Premium, the license key is stored in the SQLite settings table under premium_license_key (see server/src/routes/premium.ts). The system uses this key as a Bearer token when requesting the live catalog from https://api.freellmapi.co/v1/latest. This authentication mechanism ensures that only valid subscribers can access the time-sensitive model metadata.

The Catalog Sync Service

The core logic resides in server/src/services/catalog-sync.ts. The startCatalogSync() function initiates a background job that runs every 12 hours (SYNC_INTERVAL_MS = 12h). Each iteration calls syncCatalog(), which executes the following sequence:

1. Constructs a URL with an optional since parameter for incremental updates
2. Fetches the catalog with a 20-second timeout
3. Verifies the response signature using a pinned Ed25519 public key (catalogPublicKey()) to prevent tampering
4. Validates the JSON structure against the isCatalog schema
5. Compares the version against MIN_CATALOG_VERSION = '2026.06.07'
6. Applies the catalog to the local SQLite database via applyCatalog()
7. Caches the result in SETTING_APPLIED_JSON for offline restarts

If signature verification fails, the download is discarded entirely (lines 19-22 in catalog-sync.ts), maintaining system integrity.

Routing and Model Availability

The router (server/src/services/router.ts) reads model metadata directly from the models table. Because the live catalog updates this table automatically through applyCatalog(), the routing pipeline—including fallback chains, stickiness logic, and rate-limit ledgers—gains immediate access to new free-tier models and provider-specific quirks without code changes.

User Interface Integration

Users manage their subscription through the Premium dashboard page (client/src/pages/Premium.tsx). This React component displays the masked license key, current status via refreshLicenseStatus(), and sync state via getSyncState(). Activation requires a single POST request to /api/premium/key, which updates the database and triggers an immediate sync attempt.

Free vs Premium: A Detailed Comparison

Feature	Free Tier (Monthly Snapshot)	Premium Live Catalog
Update Frequency	Once per month (with app releases)	Every 12 hours (twice daily)
Model Freshness	Weeks behind upstream	Days behind upstream
Quota Updates	Frozen at snapshot version	Automatically refreshed
Offline Availability	Always available (bundled JSON)	Falls back to cached catalog if service unreachable
Cost	$0	$19/year or $49 lifetime
Security	Local file only	Ed25519 signature verification required

Working with the Premium API

Checking Premium Status

To verify if a license is active, query the status endpoint:

import fetch from 'node-fetch';

async function getPremiumStatus() {
  const r = await fetch('http://localhost:3001/api/premium');
  const data = await r.json();
  console.log('Premium enabled:', data.hasKey);
  console.log('License plan:', data.license?.plan);
  console.log('Current catalog tier:', data.catalog.tier);
}

getPremiumStatus();

This corresponds to the premiumRouter.get('/') handler in server/src/routes/premium.ts.

Activating a License Key

Activate Premium programmatically using cURL:

curl -X POST http://localhost:3001/api/premium/key \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR-LICENSE-KEY"}'

This endpoint is implemented in premiumRouter.post('/key') within server/src/routes/premium.ts.

Forcing a Manual Sync

Trigger an immediate catalog refresh outside the 12-hour schedule:

curl -X POST http://localhost:3001/api/premium/sync

This calls the sync logic defined in server/src/services/catalog-sync.ts on demand.

Internal Sync Implementation

Developers integrating FreeLLMAPI into custom servers can initialize the background service:

import { startCatalogSync } from './services/catalog-sync.js';

// Initialize at server startup
startCatalogSync();

This function manages the persistent timer and graceful shutdown handling, ensuring the catalog stays current without blocking the main thread.

Is the Premium Live Catalog Worth It?

For hobbyists running occasional inference jobs, the free monthly snapshot provides sufficient coverage of stable models. However, the Premium tier becomes essential if you rely on the newest free-tier releases (such as recent Gemini Flash or Groq Llama 3 variants) or need automatic quota increases when providers raise their limits.

The $19 annual fee ($49 for lifetime access) essentially purchases a near-real-time feed of free model availability. The system gracefully degrades—if the catalog service is unreachable, FreeLLMAPI falls back to the last cached version—so reliability concerns are minimal. The Ed25519 signature verification ensures that even though the catalog travels over the network, its integrity is cryptographically guaranteed.

Summary

• The Premium Live Catalog replaces FreeLLMAPI's static model list with a signed, auto-updating feed from api.freellmapi.co.
• Authentication uses a Bearer token stored in the SQLite settings table and verified on every sync.
• Updates occur every 12 hours via startCatalogSync() in server/src/services/catalog-sync.ts, with Ed25519 signature verification.
• New models appear within days of upstream release, compared to weeks for the free snapshot tier.
• Pricing is $19/year or $49 lifetime, targeting users who need cutting-edge free models without manual updates.

Frequently Asked Questions

What happens if the Premium catalog service goes offline?

FreeLLMAPI maintains the last successfully applied catalog in the SETTING_APPLIED_JSON cache. If the live service is unreachable, the system automatically falls back to this cached version via reapplyCachedCatalog(), ensuring continuous operation even without internet connectivity.

How does FreeLLMAPI verify the authenticity of the live catalog?

Every catalog response is signed with an Ed25519 private key. The syncCatalog() function in server/src/services/catalog-sync.ts verifies this signature against a pinned public key (catalogPublicKey()) before applying any changes. If verification fails, the update is discarded and the local database remains unchanged.

Can I use the Premium Live Catalog with a self-hosted instance?

Yes. The Premium tier is designed specifically for self-hosted deployments. You provide your license key via the dashboard (client/src/pages/Premium.tsx) or API, and the background sync service handles the rest. The code path is identical whether running locally or in production.

What's the difference between the free snapshot and the live catalog's update frequency?

The free tier updates only when you install a new FreeLLMAPI release (typically monthly). The Premium tier checks for updates every 12 hours (twice daily), meaning new free-tier models and quota increases appear within days rather than weeks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}