API surface

Cloud separates APIs by runtime. Use the entry point for the code you are writing.

Supported means application code may depend on the documented use. It does not make every symbol in a mixed barrel an application API. Platform-owned is for Cloud itself. Advanced paths are public exports, but application code should use them only when a feature guide gives the exact import. Preview means the contract may still change before its feature is released, and such changes are not treated as breaking until then.

Application entry points

Use the barrels above by default. Use a subpath when the specialized-entry table below links its feature guide.

Core's app bar administration uses railShortcuts from @k2b/cloud/services and the RailAdminSchema, RailAdminInputSchema, RailAccessSchema, RailAdminState, and RailAdminEntry contracts from @k2b/cloud/contracts. These are platform-owned. Applications receive the resolved navigation through Layout; see Global app bar shortcuts.

Define the application

Import defineApp() from the package root:

import { defineApp } from "@k2b/cloud";

The returned application's ssr renders pages and exposes ssr.access for browser-route rejections and ssr.error(c, status, options?) for terminal HTML errors. See SSR pages and routing.

The root also exports the types bound to an application declaration. This includes typed settings and notification definitions, and skill() with AppSkillDefinition for Assistant Skills. Registry, heartbeat, and runtime-composition exports from the same barrel are platform-owned.

See Define an application.

PanelLayout and PanelLayoutProps from @k2b/cloud/ssr render an application's provider page with its request locale and the embedded panel runtime. See Panels.

Handle server requests

Import request APIs from @k2b/cloud/server:

import {
  type AppContext,
  auth,
  middleware,
  respond,
  v,
} from "@k2b/cloud/server";

This entry point contains Hono context types, middleware, actor helpers, validation, resource access, and response helpers. buildMetadata holds the Cloud version and release label of the running application's build, for example to show the version on a settings page.

For an internal endpoint using signed Cloud invocations, the same barrel exports requireInvocation and InvocationExpectation. Supply the expected target app, operation, and schema hash. The middleware verifies the invocation and resolves current authority into the request context; the handler must still authorize access to its domain resources. It does not replace operation idempotency.

A dashboard widget handler reads the size and validated settings the board asks for with getWidgetRequest(c) from the same barrel; see Dashboard widgets.

loadPendingApprovals(c, query) loads an approval page during SSR from this entry point. Pass it as initial to the shared Approvals component. See Show approvals in your app.

For a slow handler, setRequestTimeout, REQUEST_IDLE_TIMEOUT_SECONDS, and REQUEST_IDLE_TIMEOUT_MAX_SECONDS control the bounded request idle timer; see Answer slow requests.

See Server APIs for the request path.

The widget setting types WidgetSettingField, WidgetSettingsDeclaration, WidgetSettingValue, and WidgetSettings, and the limits WIDGET_SETTINGS_MAX_FIELDS, WIDGET_SETTING_MAX_OPTIONS, WIDGET_SETTING_TEXT_MAX_LENGTH, WIDGET_SETTING_NAME_MAX_LENGTH, WIDGET_ID_MAX_LENGTH, WIDGET_KEY_MAX_LENGTH, WIDGET_REQUEST_MAX_ENTRIES, WIDGET_REQUEST_MAX_ID_LENGTH, and WIDGET_REQUEST_MAX_BYTES come from @k2b/cloud/contracts; @k2b/cloud/browser/widgets re-exports the types. See Declare settings.

Core approval routes

These routes require a user-backed actor.

Use platform services

Code outside an HTTP request uses asynchronous feature services:

import { logger } from "@k2b/cloud/services";

const log = logger("inventory");
log.info("Import completed", { itemCount: 42 });

Use the capability guide to choose the narrow API:

• Settings: SettingUnreadableError, SettingRead, and StoredSettingState from @k2b/cloud/services; app.settings.read() reports stored state before a partial update.
• Outgoing mail: mail.profiles(), mail.send(), mail.enqueue(), mail.list(), and mail.readableApps() from @k2b/cloud/services, with mail contracts and PlatformPermission from @k2b/cloud/contracts.
• Notifications
• Logging: logger() and redactSensitivePath() for safe request-path logging.
• App capabilities: cloudResourceHref(ref) from @k2b/cloud/contracts and cloudResourceUrl(ctx, ref) from @k2b/cloud/cli supply resource permalinks.
• Universal search
• Document extraction
• Secrets and persistent state: requestPublicHttps() for server-side requests to a URL that a person, an administrator, or remote content chooses; resolvePublicNetworkAddresses(), NetworkTargetBlockedError, and pinnedNetworkLookup() from @k2b/cloud/services/network-security for other transports.
• Operator-approved internal targets: createAllowedNetworkFetch(allowlist, { lookup?, resolve?, request? }?) from @k2b/cloud/services supplies a fetch-compatible streaming HTTP/HTTPS transport: it refuses URL user information, resolves once, pins the connection without proxies, preserves Host/TLS identity and repeated response headers, and propagates guard refusals. Redirects are never followed (redirect: "error" rejects a 3xx; other modes return it); non-identity encoding is rejected. Request normalization supports streaming bodies; the real Response streams until completion or cancellation. Signals cover lookup through response streaming, and callers own timeouts, limits and retries. Other internal transports use resolveAllowedNetworkAddresses() from the same entry point with a NetworkAllowlist parsed by parseNetworkAllowlist() or parseNetworkAllowlistEnv(variable, entries) (errors name the env variable) from @k2b/cloud/shared; isAllowlistedNetworkAddress() there matches IP networks without DNS. Entries come only from the application's operator-controlled env registry: exact host names, strict IPv4/IPv6, or canonical CIDRs. Host entries trust all validated answers; reserved names require a host entry. IPv4-mapped IPv6 also matches IPv4 networks; NAT64 and other embeddings require IPv6 entries. Failed or empty lookups still refuse. isNetworkTargetBlocked(hostname, allowlist, { resolve?, timeoutMs? }) from @k2b/cloud/services/network-security and @k2b/cloud/services supplies a save-time hint: only policy refusals return true; lookup failures and the default five-second timeout return false. Every request still rechecks and pins its target.

Raw stores, runtime starters, gateway telemetry, migrations, and platform composition helpers from the same barrel are maintainer APIs unless a guide names them.

linuxIdentities is a platform-owned administration service from this barrel. It checks administrator access on reads and writes. See Linux identities for configuration, explicit provisioning, and the compatible FreeIPA mirror.

accountIdentities is the supported application read service for the acting user, effective groups, provider availability and administrator-only paginated identity inventories. It does not allocate identities or track filesystems. See Account administration API for actor requirements and the limits of Cloud's FreeIPA inventory.

readAccountCategoryPolicy supplies server-side presentation settings; isAccountCategoryAllowed is for platform-owned credential eligibility checks, not application resource authorization. The browser-safe contracts barrel exports AccountCategory, AccountCategoryPolicySchema, accountCategory and accountCategoryLabel. See Account types for their use.

The contracts barrel also exports the versioned app-approval input schemas, signing-message helpers and protocol limits for independent authenticator clients. Action approval schemas, APP_ACTION_LIMITS, and the Action digest helpers support the signed inbox, action, and act commands. appApproval, readAppApprovalConfig and the AppTerminalLogins hook type in the services barrel are Core-owned maintainer surfaces, not general application authentication. Use the app approval HTTP contract for external clients.

For matching files, @k2b/cloud/contracts exports FileProviderContext, FileProviderContextSchema, FileProviderContextListInputSchema, FILE_PROVIDER_CONTEXT_MAX_REFS, fileProviderContextList, and fileProviderAcceptsContext. The existing base file-provider contract stays unchanged.

Share types with the browser

Export the Hono router type from the server. Use it with the browser client.

import { api } from "@k2b/cloud/browser";
import type { InventoryApi } from "../server";

export const inventoryApi = api.create<InventoryApi>({
  baseUrl: "/api/inventory",
});

See Browser clients and mutations.

Use query and mutation from @k2b/stdlib/solid for owner-local reads and user-initiated writes. See Server-backed state.

The clipboard, copyToClipboard, url, and isImageUrl exports are utility helpers outside the documented typed-client contract. Do not choose them as application APIs unless a guide names them.

Mixed barrels

Some barrels serve more than one audience. Use this boundary instead of inferring support from autocomplete.

For theme-aware server work, readThemeFromCookieHeader() returns a resolved CloudTheme (light or dark); for Automatic it is a best-effort hint that can be stale. readThemePreferenceFromCookieHeader() returns a CloudThemePreference (light, dark, or system). Both readers and types come from @k2b/cloud/shared. See Follow the person's theme.

@k2b/cloud/config exports env.APP_SECRET, env.PORT, env.IS_DEVELOPMENT, and env.ADMIN_LOGIN_TOKEN. The runtime configuration guide documents all process variables; that larger list is not the shape of env.

Evaluate Markdown table cells

Import evaluateTableCell(row, column, context) and EvalResult from @k2b/cloud/shared when a chart or another derived view must use the same values as a Markdown table. Row and column indices are zero-based. The context contains headers, raw rows, currentRow, and currentCol.

import { evaluateTableCell } from "@k2b/cloud/shared";

const context = { headers: ["Amount"], rows: [["+1.2e2"]], currentRow: 0, currentCol: 0 };
const result = evaluateTableCell(0, 0, context); // { kind: "ok", value: 120 }

A plain cell becomes a number only when its whole text is one decimal number, including optional sign and exponent. Dates stay text. Formula cells return the evaluated value or a structured error. Check result.kind before using its value. Use isTotalRow(row) from the same entry point to omit total rows from a derived chart while keeping the full table in the evaluation context.

Specialized entry points

View readers and types are exported from @k2b/cloud/ai/browser and @k2b/cloud/ai: CloudAiChartView, CloudAiGroupView, CloudAiTableView, CloudAiExplorerView, CloudAiExplorerRequest, CloudAiStatsView, CloudAiDetailsView, CloudAiViewReference, CloudAiView, CloudAiViewSummary, CloudAiViewSummarySchema, parseCloudAiView, checkCloudAiView, cloudAiViewSummary, cloudAiViewTable, cloudAiStatsTiles, cloudAiDetailsRows, cloudAiTableTsv, isAiViewFile, isAiViewPath, parseCloudAiChartToolView, cloudAiExplorerControls and cloudAiExplorerState, plus the view directory, suffix, byte and table limits. Both entry points expose CLOUD_AI_STATS_MAX_ITEMS (6), CLOUD_AI_GROUP_MAX_CHARTS (6), CLOUD_AI_VIEW_MAX_MARKS (3,840), CLOUD_AI_CHART_MAX_SERIES (8), CLOUD_AI_CHART_MAX_VALUES (480), CloudAiChartInput, CloudAiChartInputSchema, parseCloudAiChartInput, cloudAiChartSchema, cloudAiAppChartSchema, cloudAiNumberFormatSchema, cloudAiFormatSchema and CloudAiNumberFormat, CloudAiDateFormat, CloudAiFormat. cloudAiAppChartSchema reads the same chart input for apps without the chat's size and fit limits; missing or non-finite data values become NaN, which the renderer leaves out. Server integrations save run results with createAiConversationView and receive AiViewInvalidError for invalid specs. See Tools and approvals for validation and groups.

Custom chart hosts use browser exports cloudAiChartRenderOptions, cloudAiChartLegend, cloudAiChartRows, cloudAiChartTable, cloudAiChartTooltip, cloudAiChartMarkKey, cloudAiChartReferenceMark, cloudAiChartXValueFormat, cloudAiNumberFormatters, cloudAiChartMarks and chartDrawingIssue, with CloudAiChartColumn, CloudAiChartRow and CloudAiChartTable. These map validated chart input to rendering, legend, comparison marks and locale-formatted rows; cloudAiChartTooltip(columns, row) turns a row into the tooltip the chat shows, so every host tells the same story. A chart's optional tooltip: {label?, format?} names and formats the value in tooltips and table rows; axes keep their own formats. ChartExplorer from @k2b/ui accepts legend entries typed as ChartLegendEntry ({label, color, style?, reference?}) for a wrapping legend inside its fixed height; see Chart presentation and controls.

@k2b/cloud/ai exposes AiTaskRequestSchema, AiTaskRequest, AiTaskRequestInput, and executeAiTask for bounded text generation, classification, and extraction. The schema and types are also available from @k2b/cloud/ai/browser. See Structured and background AI for execution, model access, and usage accounting.

Every app-facing specialized row has a guide. Platform-owned and Advanced rows are exported for Cloud itself or for a narrowly documented integration; their presence is not an application support promise.

Preview surfaces

The mobile app is not released yet, so its part contract and the platform exports behind it are Preview. Their guides say so at the top.

Platform-owned and limited surfaces

“Limited” means the path is exported but not part of the documented web application contract. It is not a promise of instability.

Compatibility-only surfaces

See Deprecations for migration steps.

Avoid internal imports

Do not import from package source paths such as:

import { something } from "@k2b/cloud/src/...";

Those paths are implementation details.

requiresAuth and the other requires* values describe OpenAPI security. They do not protect a route. Use auth middleware.

The @k2b/cloud/ai export CODE_SOURCE_TOOLS and its CodeSourceToolName type define the flat inputs for direct Assistant server tools. See Assistant code tools for loading and execution. createCodeCapabilityTransport and CODE_CAPABILITY_TOKEN_HEADER on this entry point are platform-owned managed-host helpers, not application APIs. They keep the turn-bound callback credential outside the sandbox and route capability calls through Core; see App capabilities.

PDF applications use renderHtmlToPdf, renderFacturXHtmlToPdf and attachPdfFiles from @k2b/cloud/services for HTML conversion, invoice XML embedding and ordinary file attachments. preparePdfImage and its input, variant, result, and error types are available from @k2b/cloud/services and @k2b/cloud/services/pdf for bounded print image preparation. See PDF and templates for their input, access, cancellation and deployment responsibilities.

Help surfaces

@k2b/cloud/ssr/islands exports Layout.HelpPage / LayoutHelpPage for full-page and embedded readers, plus Layout.HelpDocuments / LayoutHelpDocuments and openLayoutHelpDialog. @k2b/cloud/ssr exports LayoutHelpPanel with LayoutHelpPanelProps for server HTML with small interaction islands. Render it in a server page, such as inside PanelLayout, never inside an island. Applications normally use the automatic Help registration. openLayoutHelpDialog() first opens Core's provider in the slot and falls back to a dialog when no slot accepts it. See In-product Help.

Workspace navigation

@k2b/cloud/ssr/WorkspaceNavigation.island supplies SSR-first workspace links. @k2b/cloud/ssr/islands exports WorkspaceNavigationProvider and provideWorkspaceNavigation for reactive navigation owned by an application island. See Application shells.

The standalone UI exports createNavigation, Navigation, NavigationItem, NavigationController, NavigationOptions, NavigationProps, findNavigationItem, BottomSheet, BottomSheetProps, bottomSheetOptions, and bottomSheetAdaptiveOptions. See BottomSheet for choosing a bottom-edge sheet or an adaptive decision dialog.

@k2b/cloud/browser/commands exports openCommand, registerCommandHandler, registerContextAwareCommand, and consumeCommandLink for interactive Commands and context actions in the global palette. @k2b/cloud/capabilities exports resolveCommand for authenticated HTTP clients that need an entry URL.

@k2b/cloud/contracts also exports isCommandPath to check Cloud paths. Import it from @k2b/cloud/contracts/command-path to use the check without loading validators.

Panel page context

Use readPanelContext(c) from @k2b/cloud/ssr for a provider's first server render. Browser code uses getContext() and onContextChange() from @k2b/cloud/browser/panel; host pages with in-document place changes use publishPageContext(). PanelPageContext and its strict schema are exported from @k2b/cloud/contracts. See Panels for consent, ordering, and the rule that refs never grant access.