Admin

System-level AI maintenance. Day-to-day billing administration (usage profiles, budgets, subscriptions) lives in Usage & Credits and Subscriptions.

POST /api/_ai-refresh-cache

Force an immediate License Manager sync, refreshing the local entitlement cache. Normally the cache refreshes on a schedule; use this to pick up changes right away or to recover after a sync failure.

The handler runs the live License Manager round-trip, then reads back the per-tenant AiEntitlementCache singleton and returns its state so callers can confirm the sync landed.

Authentication: Required (session)

Pre-blocks: permission.ai.manage

permission.ai.manage delegates to the billingManage global permission; superusers pass via the superuser fallback.

Request Body:

Field	Type	Required	Description
progress	string	No	Progress-channel id for streaming sync progress

Response:

Responds 200 with the resulting cache state as a HAL document. creditBalance is the License-Manager-reported pool ({ included, used, remaining }), or null before the first successful sync.

Field	Type	Description
success	boolean	true when the cache was read back after the sync attempt
syncedAt	date | null	Timestamp of the last successful sync, or null before the first
creditBalance	object | null	LM-reported pool (included / used / remaining), or null before the first successful sync

Refresh the AI entitlement cachePOST /api/_ai-refresh-cache

Forces an immediate License Manager sync and returns the resulting cache state: { success: true, syncedAt, creditBalance }. creditBalance is the LM-reported pool ({ included, used, remaining }) or null before the first successful sync. Optional payload field `progress` is a progress-channel id for streaming sync progress. Requires permission.ai.manage (superusers pass). Responds 200.

Request body

{}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/_ai-refresh-cache"
    }
  },
  "success": true,
  "syncedAt": "2026-01-15T16:20:00.000Z",
  "creditBalance": {
    "used": 12340,
    "included": 50000,
    "remaining": 37660
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

What the sync refreshes

A refresh pulls the latest state from the License Manager into AiEntitlementCache:

• Entitlement JWT the signed token that gates AI access and carries provider API keys
• Credit pool balance included / used / remaining credits
• Resource-type rate card credit rates used for local metering
• Models the available model list
• Subscription & billing config current subscription and auto-replenish/alert settings

It also drains any unreported usage events to the License Manager as part of the sync.

Sync health

License Manager connectivity is surfaced on the usage summary so the UI can warn when the license server is unreachable. See the sync block of GET /api/usage:

Field	Meaning
syncedAt	Timestamp of the last successful sync
lastSyncFailedAt	null when the most recent attempt succeeded; set when it failed
lastSyncFailureCode	One of lm_unreachable, lm_unavailable, lm_error, license_not_recognized

Troubleshooting AI access

If users cannot use AI features, confirm AI is enabled for the tenant, run a refresh to re-sync the entitlement JWT, and check the credit pool balance via GET /api/usage. A 402 Payment Required with a code indicates which limit was hit. See the enforcement flow.