Integration · Developer tool

Delivery API and SDK

Every published page and entry is readable over the BetterCMS Delivery API, and @bettercms-ai/sdk is the typed client for it. Create a client against a workspace, then read one page with getContent, a page of results with listContent, or every result with listContentAll, which follows pagination for you. It is plain TypeScript with no framework attached, so it runs in a build script, a worker or a framework nobody has written an adapter for.

Package
@bettercms-ai/sdk
Shape
REST, read only
Types
Bundled, no @types package

Set it up

Four steps, and the fourth is the one that stops a rate limit becoming an outage.

  1. 01 Install the client
  2. 02 Create a client
  3. 03 Read content
  4. 04 Handle the errors by code

Images have their own builder. @bettercms-ai/image-url assembles URLs against the media transform endpoint with width, height, format, quality, fit and dpr, and every method returns a new builder so a chain is safe to fork.

  1. 01

    Install the client

    TypeScript declarations ship with the package. There is no separate types package to add.

    terminal
    npm install @bettercms-ai/sdk
  2. 02

    Create a client

    A workspace is the only required option. An API key is optional for published content and required for anything scoped.

    lib/cms.ts
    import { BetterCMS } from "@bettercms-ai/sdk";
    
    export const client = BetterCMS.site({
      workspace: "my-workspace",
      apiKey: process.env.BETTERCMS_API_KEY,
    });
  3. 03

    Read content

    getContent takes a slug. listContent is paginated and returns items with hasNextPage and totalPages. listContentAll is an async iterator that follows pagination, with an all method when you want a capped array instead.

    read.ts
    const page = await client.getContent("home");
    
    const result = await client.listContent({ page: 1, perPage: 20 });
    
    for await (const item of client.listContentAll()) {
      console.log(item.entry.title);
    }
    
    const top = await client.listContentAll().all({ limit: 500 });
  4. 04

    Handle the errors by code

    Failures throw BetterCMSError with a semantic code, so a 404 and a rate limit are different branches rather than the same string match.

    CONTENT_NOT_FOUND, UNAUTHORIZED, FORBIDDEN, RATE_LIMITED, INTERNAL_ERROR and NETWORK_ERROR are the ones to handle.

    read.ts
    import { BetterCMSError, ErrorCodes } from "@bettercms-ai/sdk";
    
    try {
      await client.getContent("does-not-exist");
    } catch (err) {
      if (err instanceof BetterCMSError) {
        if (err.code === ErrorCodes.RATE_LIMITED) backOff();
        if (err.code === ErrorCodes.CONTENT_NOT_FOUND) return null;
      }
      throw err;
    }

What it does not do

  • There is no GraphQL endpoint

    The Delivery API is REST. If a GraphQL layer is a requirement, that is a real gap and it is better known now than after a proof of concept.

  • Delivery is read only

    This client reads published content. Writing goes through the Management API, which is what the dashboard and the MCP server use, and it takes a content:manage key.

  • It does no caching of its own

    The SDK is a thin typed client. The Next.js adapter adds cache aware reads because Next patches fetch; the plain SDK leaves caching to you.

  • It is rate limited

    A burst of reads can return RATE_LIMITED. Handle that code with a back off rather than a retry loop, especially in a build script that walks every entry.

Questions people ask

  • No. The BetterCMS Delivery API is REST, and @bettercms-ai/sdk is the typed client for it. If your architecture requires GraphQL, that is a genuine gap rather than something to work around, and it is worth raising before a proof of concept rather than during one.

  • Yes. That is what the SDK is for. It is plain TypeScript with no framework dependency, so Nuxt, SvelteKit, Remix, a build script or a worker all read content the same way. What you lose without an adapter is the framework specific work: cache integration, draft preview wiring and ready made block components.

  • The client takes a workspace and an optional API key. Published content is readable with the workspace alone; anything scoped, including drafts, needs a key with the right scope. Keep server keys on the server. Both framework adapters keep them out of the client bundle for exactly this reason.

Your next website starts here

See BetterCMS running on your pages, not on a sample site.