The Utilities API provides a set of essential maintenance and support services that keep the SveltyCMS environment healthy and performant. It manages cache invalidation, recoverable data via the Trash, transactional email, API documentation, version checking, and diagnostics.

⚡ Quick Reference

1. OpenAPI & API Documentation

OpenAPI 3.1.0 Specification

Generates the full OpenAPI 3.1.0 specification dynamically. Admin-gated to prevent AI reconnaissance blinding.

Endpoint: GET /api/openapi.json

Swagger UI Documentation Browser

Serves an interactive Swagger UI that loads the spec from /api/openapi.json.

Endpoint: GET /api/docs

2. Maintenance & Cache

Clear System Cache

Invalidates the entire cache for the current tenant.

Endpoint: POST /api/cache/clear
Payload: {} (optional — the category field is accepted but the implementation currently clears all categories regardless)

Cache Statistics

Returns live cache metrics including hit rates, size, and eviction counts.

Endpoint: GET /api/cache/stats

3. Recovery (The Trash)

SveltyCMS implements a “Soft Delete” pattern. Deleted entries are moved to the Trash before being permanently purged.

• List Trash: GET /api/trash — Returns a paginated list of items currently in the trash for the current tenant. Accepts ?limit= query param (default 50, max 200).
• Restore: POST /api/trash/restore — Returns an item to its original collection and restores its original status.
  • Payload: { "collectionId": "...", "entryId": "..." }
• Empty Trash: Not currently implemented via the API.

4. Communication

Transactional Email

Send emails directly via the API using the system mail service.

Endpoint: POST /api/send-mail
Payload:

{
  "to": "user@example.com",
  "subject": "System Alert",
  "templateName": "alert",
  "props": { "message": "High CPU usage" },
  "languageTag": "en"
}

5. System Diagnostics

Version Check

Checks for available updates. Authenticated (unlike the public /api/system/version).

Endpoint: GET /api/version-check — dispatcher alias of GET /api/system/version/check.

Returns the raw update-check payload (currentVersion, latestVersion, updateAvailable, checkedAt, and error when GitHub is unreachable). The canonical route wraps the same payload in the standard { success, data } envelope.

Configuration Sync

Debug / Diagnostics

Returns system diagnostics including uptime, memory usage, and environment info. Admin-only.

Endpoint: GET /api/debug

Marketplace

Offline-first in-app catalog for themes, plugins, and related packages (Phase 2). Backed by MarketplaceService — local themes/plugin stubs always, remote marketplace.sveltycms.com when reachable (via marketplace-client, 30 min cache).

List catalog — GET /api/marketplace

Response (data):

Install — POST /api/marketplace/install (admin only)

{ "itemId": "theme-or-package-id" }

Today installs themes via adminThemeService; remote one-click package install remains a Phase 2 follow-up. See Marketplace architecture.

UI: Config → Extensions → Marketplace (marketplace-view.svelte).

6. Remote Media & SEO Tools

Remote Video Metadata

Fetches metadata for third-party video providers (YouTube, Vimeo) with server-side SSRF validation and safe egress URL filtering.

Endpoint: POST /api/remote-video
Payload:

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Response (data):

{
  "provider": "youtube",
  "videoId": "dQw4w9WgXcQ",
  "title": "Video Title",
  "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg"
}

SEO Link Suggestions

Provides fast internal linking recommendations for content editors by analyzing content text and keyword frequency across published entries within the active tenant.

Endpoint: POST /api/seo/link-suggestions
Payload:

{
  "content": "<p>Article text containing keywords...</p>",
  "collectionId": "posts",
  "currentId": "entry-123",
  "focusKeyword": "sveltycms"
}

Response (data):

{
  "suggestions": [
    {
      "title": "Getting Started with SveltyCMS",
      "url": "/posts/getting-started",
      "score": 2.5,
      "collection": "Posts"
    }
  ]
}

7. The Mechanics

Utility Dispatcher

The utility.ts handler manages a wide range of disparate system helper tasks. It acts as the primary interface for scheduled maintenance jobs, cross-system communication, and editor assistive tooling.

Access Control

All utility namespaces are gated via the dispatcher’s centralized ENDPOINT_PERMISSIONS mapping (see the Quick Reference table above):

• Only cache, debug and security map to system:admin.
• trash maps to collection:read/collection:write, send-mail to system:settings, version-check, marketplace and openapi.json to system:read/system:settings.
• Editor tools (remote-video, seo) require collection:read — not media:read.
• Unmapped namespaces (e.g. docs) fail closed with 403 Forbidden.
• Individual handlers perform defense-in-depth authorization checks.

Related Documents

• Marketplace architecture
• System Reference (system.ts)
• Content Reference (content.ts)
• API Coverage Report