SDK reference

@foldkit/embed for the browser, @foldkit/node for your server. Both zero-dependency.

Package	Runs in	Size
`@foldkit/embed`	The browser. ESM, CJS and UMD.	~14 KB minified, ~5 KB gzipped
`@foldkit/node`	Node 18+. Uses only node:crypto and global fetch.	Negligible

Foldkit.mount(target, options)

Creates the iframe, waits for the editor to boot, and resolves with the handle. target is a CSS selector or an element. Rejects with a FoldkitError if the editor does not become ready.

Option	Type	Notes
`token`	`string \| () => string \| Promise<string>`	An `es_…` session token. Pass a function to enable silent renewal.
`publishableKey`	`string`	The zero-backend tier. Only accepted from a verified origin.
`designId`	`string`	Open an existing design instead of starting a new one.
`tenant`	`string`	Your tenant slug. Only needed alongside `token`.
`baseUrl`	`string`	Defaults to `https://foldkit.theboxes.asia`.
`theme`	`object`	`{ primary, accent, ink, canvas, surface }`, or exact `--tb-*` tokens.
`locale`	`string`	A BCP-47 tag.
`autoResize`	`boolean`	Follow the editor’s height. Default true.
`height`	`number \| string`	Initial frame height.
`className`	`string`	Applied to the generated iframe.
`readyTimeoutMs`	`number`	How long to wait for boot. Default 30 000.
`commandTimeoutMs`	`number`	How long any one command may take. Default 30 000.

Commands

Every command returns a promise and rejects with a `FoldkitError`.

Command	Resolves with
`save()`	`{ designId, savedAt }`
`getDesign()`	`{ doc }`
`getSnapshot({ width })`	`{ dataUrl }` — a PNG of the 3D preview. Needs the preview on screen.
`loadDesign(designId)`	void
`setBoxParams({ styleId, dimensions })`	void — dimensions clamp to your configured limits.
`setTheme(theme)`	void
`setLocale(tag)`	void
`export({ kind, options })`	`{ exportId }` — resolves when the job is accepted, not when the file is ready.
`destroy()`	void — removes the iframe and every listener. Always call it on unmount.

Events

on, off and once all take (name, handler). An unknown name is ignored rather than throwing: your page pins a version and the iframe is whatever we deployed this morning, so each end has to tolerate the other knowing something it does not.

Event	Payload
`loaded`	`{ designId, tenant, permissions, features }`
`dirty`	`{ dirty }`
`saved`	`{ designId, savedAt }`
`export.started`	`{ exportId, kind }`
`export.progress`	`{ percent, stage }`
`export.complete`	`{ url, kind }`
`export.failed`	`{ message }`
`resize`	`{ width, height }`
`token.expiring`	`{ expiresAt }`
`error`	`FoldkitError`

FoldkitError

error.code       // one of the codes below
error.message    // for a human. Reworded freely — do not match on it.
error.requestId  // quote this to support

The codes, in full: invalid_key, origin_not_allowed, invalid_token, token_expired, token_already_used, tenant_suspended, insufficient_scope, rate_limited, quota_exceeded, design_not_found, internal_error. What each one means and what to do about it is on the errors page.

@foldkit/node

import { Foldkit, verifyWebhookSignature, signWebhookPayload } from '@foldkit/node'

const foldkit = new Foldkit({ secretKey: process.env.FOLDKIT_SECRET_KEY })

Method	Does
`embedSessions.create(input)`	Mints a single-use session token for one editor mount.
`designs.list(query)`	Cursor-paged list.
`designs.get(id)`	One design and its document.
`designs.update(id, patch)`	Rename, re-attribute, archive.
`exports.create(input)`	Starts an export job.
`exports.get(id)`	Status and, once completed, a fresh signed download URL.
`verifyWebhookSignature(options)`	Throws unless the delivery verifies. Takes the raw body.
`isWebhookSignatureValid(options)`	The boolean form, when you genuinely want one.
`signWebhookPayload(options)`	Produces the header we would send — for testing your own handler.

From a CDN

<script src="https://cdn.jsdelivr.net/npm/@foldkit/embed@0.1.0/dist/foldkit-embed.umd.js"></script>

The UMD build defines a global Foldkit.
Pin an exact version. @latest in a script tag is a page whose behaviour changes on a day you did not deploy.
Add a Subresource Integrity hash in production — take the SHA-384 of the file the CDN actually serves.

← Configuration

API reference →