Both access patterns are derived from a single, unified OpenAPI 3.1.0 contract, ensuring 1:1 parity and maximum flexibility for any setup:

• External HTTP / GraphQL API — The secure, public-facing interface with the full middleware stack (auth, rate limiting, CORS, etc.). Now featuring automated population and real-time subscriptions.
• Internal Local SDK — A zero-overhead, server-side-only API for maximum performance in your SvelteKit backend code.

Recommendation: In all server-side code (+page.server.ts, actions, hooks, etc.), prefer the Local SDK unless you have a specific reason to test the full HTTP stack.

When to Use Which

Why the Local SDK Exists

The Local SDK (src/services/sdk/index.ts — the LocalCMS class) is a high-performance facade that:

1. Eliminates overhead: No network stack, JSON parsing, or serialization.
2. Bypasses external security: Safely skips WAF and rate-limiting because it runs with server privileges.
3. Calls Core Logic: Executes the exact same modifyRequest pipeline as the HTTP layer.
4. Maintains Consistency: Automatically triggers cache invalidation and real-time events (SSE).
5. Unified Context: Respects the same tenant isolation and permissions as the external API.

What is not faster than LocalCMS (2026)

gRPC / protobuf / HTTP/3 beat JSON-over-HTTP between processes. They do not beat an in-process function call. Spotify’s published backend work (gRPC as the default service-to-service protocol, proxyless xDS mesh) is for thousands of Kubernetes services talking across the network — not for a server talking to itself. In this CMS the analog is:

A .remote.ts that event.fetch("/api/...") re-enters the HTTP pipeline (auth, WAF, JSON) and throws away the LocalCMS advantage. Remotes must call LocalCMS the same way +page.server.ts does (getRequestLocalCMS()). User profile, settings groups, collection save/delete remotes, and dashboard health follow that path.

HTTP/3 and QUIC still matter for clients on lossy networks; they do not replace LocalCMS on the server.

Measured Local SDK vs HTTP (SQLite, self-measured 2026-08)

Same machine, same harness (bun test tests/benchmarks/). The Local SDK is two to three orders of magnitude faster than the HTTP cold path because the HTTP middleware stack (auth, RBAC, security headers, serialization) is the dominant cost — not the database.

Example: Local SDK Structure

The cms (LocalCMS) object provides a unified, typed interface to all system capabilities:

// Content Management
await cms.collections.find("posts", { limit: 10 });
await cms.collections.create("posts", { title: "New" });
await cms.media.list({ folderId: "uploads" });

// Identity & Access
await cms.auth.listUsers({ tenantId });
await cms.websiteTokens.create({
  name: "API Key",
  permissions: ["content:read"],
  user,
  tenantId,
});

// System & Infrastructure
await cms.system.settings.getAll();
await cms.system.getHealth();
await cms.widgets.list();

// Collection Builder organizational tree (gui-save, manifest, SSE)
await cms.contentStructure.saveGuiStructure(
  [{ type: "move", node: { path: "/collection/posts", parentId: "cat-1" } }],
  { tenantId },
);

// Direct adapter access (escape hatch)
const raw = await cms.db.crud.findMany("posts", {}, { tenantId });

Collections Namespace Modules (2026-08 refactor)

src/services/sdk/namespaces/collections-namespace.ts was consolidated from a ~2,100-line monolith into a thin orchestrator (~1,240 lines) with each concern living exactly once in its own module under src/services/sdk/namespaces/collections/:

Key hot-path changes:

• One-pass write field prep — prepareCollectionFields() in src/content/content-utils.ts replaces the former three-walk chain (sanitizeCollectionFields → stripNullRows → validateFieldConstraints) with a single schema walk and at most one shallow clone.
• Shared hook orchestration — applySchemaHookPipeline() (with an optional createError factory so write paths still throw AppError(400, "FIELD_VALIDATION_ERROR")) now serves both create and update instead of duplicated inline pipelines.
• Physical table names — collectionTableName() in src/databases/core/collection-name.ts is the single source for collection_<id> derivation (namespace + API handlers).
• Per-item dynamic import removed from list() (token engine now a memoized singleton); findById schema-cache key casing fixed; findStreaming now shares the schema cache.
• Widget pipeline — modifyRequest caches active widgets on the fields array; DateTime uses a static toISOString import (no per-field dynamic import).
• Cross-chunk singletons — responseCache, webhook, and automation services bind to globalThis so Rolldown chunks share one instance.

Security invariants (unchanged)

The refactor is behavior-preserving by design. The write path still enforces, in order: field sanitization (stored-XSS prevention) → constraint/numeric validation → schema hooks → assertWriteAllowed for non-admin writers → persist → detached side effects. Read paths still clamp publication visibility (resolvePublicationFilter + status bound into the DB query), keep the per-filter cache suffix (a cached “all” document can never reach a clamped caller), and always inject tenantId. Post-write side effects (outbox, workflow, pub-sub, plugin hooks) remain best-effort and never surface to the caller.

Example: Data Loading in +page.server.ts

import { LocalCMS } from "@src/services/sdk";
import { getDb } from "@src/databases/db";
import type { PageServerLoad } from "./$types";

export const load: PageServerLoad = async ({ locals }) => {
  const cms = new LocalCMS(getDb()!);
  const posts = await cms.collections.find("posts", {
    limit: 10,
    tenantId: locals.tenantId,
  });
  return { posts };
};

Example: Bulk Operations

// Collections namespace supports bulkCreate, bulkUpdate, bulkDelete
const result = await cms.collections.bulkCreate("products", largeDataArray, {
  tenantId,
});

Technical Details

Local SDK Guarantees

• Widget/request modification pipeline (modifyRequest) runs identically to HTTP requests.
• Cache hooks, invalidation, and version bumping happen automatically.
• Real-time updates (SSE / WebSocket) are triggered for connected clients.
• Multi-tenancy, user context, and permissions are applied consistently.
• Media Intelligent Storage: Shared deduplication and loop protection logic for all uploads via cms.media.upload().
• Bulk operations: cms.collections.bulkCreate(), bulkUpdate(), bulkDelete() for high-throughput tasks.
• Direct adapter access: cms.db provides escape-hatch access to the raw IDBAdapter when the SDK namespace doesn’t cover a needed operation.

When You Might Still Use HTTP from Server Code

• Calling a completely external microservice or third-party API.
• Deliberately exercising the full external middleware (e.g., for testing or logging).
• Cross-origin or cross-instance communication.

Best Practices

1. Default to Local SDK in every .server.ts file, server actions, and hooks.
2. Avoid fetch('/api/...') inside server code — it adds unnecessary latency and stack depth.
3. Instantiate via new LocalCMS(adapter) from @src/services/sdk for clean, typed access. The instance is lightweight and safe to create per-request.
4. Use cms.db when you need raw adapter access — e.g., cms.db.system.websiteTokens.getByToken().

---

## Related

- [API Reference](/docs/development/index)
- [Getting Started](/docs/getting-started)