The SDK: what it wraps and what it doesn't
The SDK wraps seventeen route families as typed scopes, turns a 404 body into a normal result, and leaves audiences and changesets to raw fetch.
@kywi-software/sdk is a typed wrapper over part of the REST API — one HTTP client, seventeen scopes, no caching, no retries, no state. It covers reading and writing content and the surfaces around it; it does not cover targeting or release management, and knowing which half you are in saves an afternoon.
function createKywiSdk(config: KywiSdkConfig): KywiSdkScope
interface KywiSdkConfig {
baseUrl: string // e.g. 'https://cms.example.com/api/v1'
apiKey?: string // sent as Authorization: Bearer <apiKey>
token?: string // a session JWT; overrides apiKey
defaultSiteId?: string // slug or UUID, used when a call omits siteId
locale?: string // with bundles, adds the local i18n scope
bundles?: Map<string, Map<string, string>>
headers?: Record<string, string> // merged into every request
}defaultSiteId is threaded into the content, nav, site, feeds,
components and menus scopes, so those calls can omit it. Nothing else reads it — a scope
not in that list has no notion of a current site.
import { createKywiSdk } from '@kywi-software/sdk'
const kywi = createKywiSdk({
baseUrl: 'https://cms.example.com/api/v1',
apiKey: process.env.KYWI_API_KEY,
defaultSiteId: 'default',
})
const page = await kywi.content.getBySlug('pricing') // null when it isn't thereThe seventeen scopes
defaultSiteId when a call omits a site; the rest have no notion of one. An eighteenth scope, i18n, appears only when you pass both bundles and locale — it resolves strings from the map you supplied and makes no request at all.| Name | Type | Default | Description |
|---|---|---|---|
auth | /auth/… | — | login, register, refresh, forgot-password, reset-password. |
content | /content/… | — | List, get by slug or id, create, update, delete. |
nav | /nav | — | The published navigation tree. |
site | /sites/… | — | One site, all sites, and a site settings PUT. |
user | /users | — | User CRUD. |
feeds | /feeds/… | — | Feed definitions and a query endpoint. |
components | /components | — | Reusable component definitions. |
menus | /menus | — | Managed menus. |
media | /media/… | — | Upload, list, fetch, delete. |
layout | /content/by-id/:id/layout | — | A page's layout document, whole or by region. |
search | /search | — | The search index. |
versions | /content/:type/:id/versions | — | Version list, one version, restore. |
workflow | /content/by-id/:id/… | — | publish, unpublish, restore, permanent. |
categories | /categories/… | — | Flat list, tree, one category. |
forms | /forms/:slug/… | — | CSRF token, submit, read submissions. |
tree | /content/by-id/:id/children | — | Children — and three methods that do not work; see below. |
hooks | /webhooks | — | Webhook ENDPOINT CRUD only. Delivery history is not wrapped. |
What it does not wrap
Audiences, experiments, changesets, bulk operations, GraphQL, content-type introspection, webhook delivery history, cache administration, tags, comments, translations, API keys and OAuth clients have no scope. They are not missing features of the API — they are routes you call with fetch and your own types. If your integration is mostly personalization or mostly release management, the SDK will carry almost none of it.
Three tree methods to avoid
sdk.tree.getBreadcrumbs, sdk.tree.move and sdk.tree.reorder call paths the API does not register, and because of the behaviour above they fail silently. move and reorder return void, so they resolve cleanly having moved nothing; getBreadcrumbs reads data off an error body and yields undefined. Only sdk.tree.getChildren is correct.
sdk.tree.getBreadcrumbs(id) → GET /nav/breadcrumbs/:id the route is /nav/:nodeId/breadcrumbs
sdk.tree.move(id, …) → POST /content/by-id/:id/move the route is /content/:type/:id/move
sdk.tree.reorder(items) → POST /nav/reorder no such route; ordering is PUT /content/sortCall those three routes directly until the client is corrected. The paths on the right are the ones registered by the API.
siteId is always a query parameter
Including on creates. The server's create schema is strict and rejects an in-body siteId with a 400, so the client appends it to the URL instead — which is also why passing a site to a create through the data object silently does nothing useful. Set defaultSiteId once and let the six site-aware scopes use it; for what that value may be and how the server resolves it, see Site scoping and the ?siteId= contract.
List results carry hasMore from the server's own pagination meta, with an arithmetic fallback for a server older than that field. See The response envelope, pagination, and errors for the envelope the SDK is unwrapping, and Authenticating an external caller for what an apiKey can reach.