# The SDK: what it wraps and what it doesn't

URL: https://kywi-docs-production.up.railway.app/integrating/the-sdk-what-it-wraps-and-what-it-doesnt
Type: docPage

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 there

## The seventeen scopes

Each scope and the route family behind it. The content, nav, site, feeds, components and menus scopes read `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.

## 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.

## A 404 comes back as a result, not an error

The HTTP client throws `KywiSdkError` for every failing status except 404, which it parses and returns as though it were data. The content scope relies on that deliberately — `getBySlug` answers `null`, `getChildren` answers `[]` — but any call that does not check gets `{"error":{"code":"NOT_FOUND","message":"Route not found"}}` handed back as a successful result. Nothing throws, nothing logs. Treat "the field I wanted is undefined" as a possible 404, not as empty data.

## 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/sort

Call 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](/integrating/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](/integrating/the-response-envelope-pagination-and-errors/) for the envelope the SDK is unwrapping, and [Authenticating an external caller](/integrating/authenticating-an-external-caller/) for what an `apiKey` can reach.
