Content SDK API Reference

createClient(config) #

Creates a content client for fetching models and entries.

import { createClient } from "@better-i18n/sdk";

const client = createClient({
  projectId: "acme/web-app",
  apiKey: "bi-your-api-key",
});

Parameters:

Returns: ContentClient

---

client.from(modelSlug) #

Start a chainable query builder for a content model. This is the primary API for fetching entries.

const builder = client.from("blog-posts"); // [!code highlight]

Parameters:

Returns: ContentQueryBuilder

The builder is immutable — every chained method returns a new builder instance. The builder is thenable: await it directly to execute a list query.

---

Query Builder Methods #

All methods return a new ContentQueryBuilder instance and can be chained in any order.

.select(...fields) #

Choose which fields to include. slug and publishedAt are always returned. When omitted, all fields are returned.

const { data } = await client
  .from("blog-posts")
  .select("title", "body", "category");

.eq(field, value) #

Filter entries by exact field value. Works for the built-in status field and any custom field.

const { data } = await client
  .from("blog-posts")
  .eq("status", "published");

.filter(field, value) #

Filter by a custom field value. Equivalent to .eq() for custom fields.

const { data } = await client
  .from("blog-posts")
  .filter("category", "engineering");

.search(term) #

Full-text search on entry titles.

const { data } = await client
  .from("blog-posts")
  .search("kubernetes");

.language(code) #

Set the language code for localized content. Falls back to the source language when the requested language has no translation.

const { data } = await client
  .from("blog-posts")
  .language("fr")
  .single("hello-world");

.order(field, options?) #

Set the sort field and direction.

const { data } = await client
  .from("blog-posts")
  .order("publishedAt", { ascending: false });

.limit(n) #

Limit the number of entries returned per page.

const { data } = await client.from("blog-posts").limit(20);

.page(n) #

Set the page number for pagination (1-based).

const { data } = await client.from("blog-posts").limit(20).page(3);

.expand(...fields) #

Expand relation fields, resolving referenced entries inline. Expanded relations appear in a relations key on each entry. The relation object's custom fields are flat on the relation object itself.

const { data } = await client
  .from("blog-posts")
  .expand("author", "category");

---

Terminal Methods #

.single<CF>(slug) #

Fetch a single entry by slug. Returns a SingleQueryBuilder<CF> which is thenable — await it directly.

const { data: post, error } = await client // [!code highlight]
  .from("blog-posts") // [!code highlight]
  .language("en") // [!code highlight]
  .single("hello-world"); // [!code highlight]

Type Parameter: CF extends Record<string, string | null> — Custom fields shape. Defaults to Record<string, string | null>. See TypeScript guide.

Returns: SingleQueryBuilder<CF> (thenable → SingleQueryResult<ContentEntry<CF>>)

await builder (list query) #

Awaiting a ContentQueryBuilder directly executes a list query.

const { data, error, total, hasMore } = await client
  .from("blog-posts")
  .eq("status", "published");

Returns: QueryResult<ContentEntryListItem[]>

---

Return Types #

QueryResult<T> #

Returned when awaiting a list query (await client.from(...)).

SingleQueryResult<T> #

Returned when awaiting a single query (await client.from(...).single(...)).

---

client.getModels() #

List all content models in the project.

const models = await client.getModels();

Returns: Promise<ContentModel[]>

---

Legacy Methods #

client.getEntries(modelSlug, options?) — deprecated #

Use client.from(modelSlug) instead.

// Deprecated
const { items, total, hasMore } = await client.getEntries("blog-posts", {
  status: "published",
});

// Preferred
const { data, total, hasMore } = await client
  .from("blog-posts")
  .eq("status", "published");

client.getEntry(modelSlug, entrySlug, options?) — deprecated #

Use client.from(modelSlug).single(entrySlug) instead.

// Deprecated
const post = await client.getEntry("blog-posts", "hello-world", {
  language: "fr",
});

// Preferred
const { data: post } = await client
  .from("blog-posts")
  .language("fr")
  .single("hello-world");

---

REST API Endpoints #

The SDK calls these REST endpoints under the hood:

All requests use the x-api-key header for authentication.

---

Types #

">

Returned by .single(). Custom fields are spread directly onto the entry via & CF — there is no nested customFields wrapper.

Base fields (always included):

Additional fields (present on single-entry responses):

Custom fields from CF are spread flat onto this object.

">

Returned in list query results. Custom fields are spread directly onto the item via & CF — there is no nested customFields wrapper.

Custom fields from CF are spread flat onto this object.

Field definition returned inside ContentModel.fields.

">

">

Returned for each key in relations when .expand() is used. Custom fields of the referenced entry are spread flat onto this object — no nested customFields wrapper.

Additional string | null keys represent the referenced entry's custom fields.

type ContentEntryStatus = "draft" | "published" | "archived";

type ContentEntrySortField = "publishedAt" | "createdAt" | "updatedAt" | "title";