# FreeLLMAPI Premium Live Catalog: Real-Time Model Updates Explained

> Discover FreeLLMAPI's Premium Live Catalog for real-time model updates. Get fresh free-tier models and updated quotas every 12 hours. Unlock continuous value with a license key.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: feature-explanation
- Published: 2026-06-24

---

**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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/catalog-sync.ts)), maintaining system integrity.

### Routing and Model Availability

The router ([`server/src/services/router.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```typescript
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/premium.ts).

### Activating a License Key

Activate Premium programmatically using cURL:

```bash
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/premium.ts).

### Forcing a Manual Sync

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

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

```

This calls the sync logic defined in [`server/src/services/catalog-sync.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/catalog-sync.ts) on demand.

### Internal Sync Implementation

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

```typescript
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.