API Reference

createClient(config)

Creates a content client for fetching models and entries.

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

const client = createClient({
  project: "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"); 

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 
  .from("blog-posts") 
  .language("en") 
  .single("hello-world"); 

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