Utilities (utility.ts)

Reference for system helper services — cache management, trash recovery, email dispatching, OpenAPI spec, Swagger UI, version checking, and diagnostics.

6/15/2026

4 min read

Edit on GitHub

On this page

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.

Important

All utility endpoints are admin-gated. Unmapped namespaces fail-closed via the dispatcher’s ENDPOINT_PERMISSIONS mapping, and individual handlers perform defense-in-depth isAdmin checks. Non-admin users receive 403 Forbidden.

⚡ Quick Reference

Feature	HTTP Endpoint	Method	Admin Only
OpenAPI Spec	`/api/openapi.json`	`GET`	✅
Swagger UI	`/api/docs`	`GET`	—
Cache Clear	`/api/cache/clear`	`POST`	✅
Cache Stats	`/api/cache/stats`	`GET`	✅
Trash List	`/api/trash`	`GET`	✅
Restore Entry	`/api/trash/restore`	`POST`	✅
Send Email	`/api/send-mail`	`POST`	✅
Version Check	`/api/version-check`	`GET`	✅
~~Config Sync~~	`/api/config_sync`	`GET`	✅
Debug / Diagnostics	`/api/debug`	`GET`	✅
Marketplace	`/api/marketplace`	`GET`	✅

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

Warning

The /api/docs (Swagger UI) endpoint is gated by admin permissions. For it to function, the docs namespace must be mapped in the API dispatcher’s ENDPOINT_PERMISSIONS in src/routes/api/[...path]/+server.ts. If the namespace is unmapped, the dispatcher fails-closed with 403 Forbidden. Ensure your deployment’s dispatcher configuration explicitly permits the docs namespace.

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"
}

Field	Type	Required	Description
`to`	`string`	✅	Recipient email address
`subject`	`string`	✅	Email subject line
`templateName`	`string`	—	Template to render (default: `generic`)
`props`	`object`	—	Template variables
`languageTag`	`string`	—	Locale for rendering (default: `en`)

5. System Diagnostics

Version Check

Checks for available updates.

Endpoint: GET /api/version-check?checkUpdates=true

Configuration Sync

Warning

Deprecated. GET /api/config_sync is deprecated and routed to GET /api/config/status. Use the new Configuration Promotion API instead. The old endpoint will continue to work via the dispatcher alias but will be removed in a future major version.

Migration: Replace GET /api/config_sync with GET /api/config/status.

Debug / Diagnostics

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

Endpoint: GET /api/debug

Marketplace

Placeholder endpoint for the extensions marketplace.

Endpoint: GET /api/marketplace

6. 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 and cross-system communication.

graph LR A[Utility API] --> B[CacheService] A --> C[Trash / ContentSystem] A --> D[Email / SystemNamespace] A --> E[ApiSpecService] A --> F[VersionCheckService] A --> G[Debug / Diagnostics]

Access Control

All utility namespaces are absent from the ENDPOINT_PERMISSIONS mapping in the API dispatcher, causing the framework to fail-closed: non-admin users receive 403 Forbidden. Individual handlers (e.g., OpenAPI, Debug) perform additional defense-in-depth isAdmin checks.