SDK Reference

Adapto CMS Client SDK#

The Adapto SDK is the data layer shared across every Adapto CMS framework starter. It handles authentication, in-memory caching, automatic retries, and content fetching through six namespaced modules.

Environment Variables#

Initialisation#

The starter projects export a pre-configured singleton from src/lib/adapto-sdk.ts.

// src/lib/adapto-sdk.ts
import { AdaptoSDK } from '@adaptocms/sdk';
import { API_URL, API_KEY, IS_DEV } from '@/config';

export const adapto = new AdaptoSDK({ apiUrl: API_URL, apiKey: API_KEY, dev: IS_DEV });

File URL Rewriting#

The SDK automatically rewrites S3 file URLs in API responses to use the Adapto CDN at media.adaptocms.com. Every url and image field in the response is already CDN-ready.

Modules#

adapto.articles#

adapto.categories#

adapto.pages#

adapto.collections#

adapto.microCopy#

adapto.languages#

Returns an ordered array of locale codes (e.g. ["en-US", "fr-FR"]). The first entry is the default language for the project.

Types#

IPaginatedResponse<T>#

interface IPaginatedResponse<T> {
  items: T[];
  total: number;   // total number of matching records
  page: number;    // current page (1-based)
  limit: number;   // items per page
  pages: number;   // total number of pages
}

IArticle#

interface IArticle {
  id: string;
  title: string;
  slug: string;
  content: string;                          // HTML
  summary: string;                          // auto-generated from first <p>, max 200 chars
  author: string;
  categories: string[];                     // array of category IDs
  tags: string[];
  language: string;                         // e.g. "en-US"
  status: 'draft' | 'published' | 'archived' | 'deleted';
  published_at: string | null;
  created_at: string | null;
  updated_at: string | null;
  media_objects_placements: IMediaObjectsPlacement[];
  custom_fields: Record<string, unknown>;
  translation_of_id: string | null;
}

IArticlePreview#

Returned by list(). Same as IArticle but omits content, media_objects_placements, and custom_fields.

ICategory#

interface ICategory {
  id: string;
  name: string;
  slug: string;
  description: string | null;   // HTML
  language: string;
  parent_id: string | null;     // null for top-level categories
  translation_of_id: string | null;
}

IPage#

interface IPage {
  id: string;
  title: string;
  slug: string;
  content: string;              // HTML
  menu_label: string | null;    // navigation label, may differ from title
  language: string;
  parent_id: string | null;
  tags: string[];
  status: 'draft' | 'published' | 'archived';
  translation_of_id: string | null;
}

ICustomCollection#

interface ICustomCollection {
  id: string;
  name: string;
  slug: string;
  description: string;
  language: string;
  fields: ICollectionField[];
  status: string;
}

ICollectionField#

interface ICollectionField {
  name: string;      // key used in item.data
  label: string;     // human-readable label
  type: 'text' | 'rich_text' | 'number' | 'boolean' | 'date'
      | 'image' | 'url' | 'email' | 'select' | 'multi_select';
  required: boolean;
  multiple: boolean;
}

ICustomCollectionItem#

interface ICustomCollectionItem {
  id: string;
  title: string;
  slug: string;
  language: string;
  status: string;
  collection_id: string;
  data: Record<string, unknown>;            // field values keyed by field name
  media_objects_placements: IMediaObjectsPlacement[];
  translation_of_id: string | null;
}

IMicroCopy#

interface IMicroCopy {
  id: string;
  key: string;
  value: string;
  language: string;
  tags: string[];
}

IMediaObjectsPlacement#

interface IMediaObjectsPlacement {
  placement_key: string;
  media_object: {
    id: string;
    file_id: string;
    url: string;
    type: 'image' | 'video' | 'audio' | 'document'
        | 'youtube' | 'vimeo' | 'tiktok' | 'instagram_reel' | 'instagram_post' | 'other';
    title: string | null;
    description: string | null;
  };
  caption: string | null;
  alt_text: string | null;
}

Translations#

Every translatable content type — articles, categories, pages, collection items, and micro copy — has a translation_of_id field. When an entry is a translation of another, this field holds the ID of the original. Original-language entries have translation_of_id: null.

Querying by language returns only entries for that locale. To group an entry with all its translations — for example, to build a language switcher — collect all entries that share the same translation_of_id or whose id matches another entry's translation_of_id.

hydrateMediaPlacements#

Articles, pages, and collection rich_text fields can contain media placeholders in the form <media-object key="placement_key"></media-object>. Call hydrateMediaPlacements to replace each placeholder with the appropriate embed HTML before rendering.

import { hydrateMediaPlacements } from '@/lib/hydrateMediaPlacements';

const html = hydrateMediaPlacements(
  article.content,
  article.media_objects_placements,
);

Supported media types and their rendered output:

Pass the hydrated string to your framework's HTML rendering directive (dangerouslySetInnerHTML in Next.js, {@html} in SvelteKit, set:html in Astro).