---
title: "SDK Reference"
url: "https://adaptocms.com/docs/sdk-reference/"
source: adaptocms.com
---

# SDK Reference

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

Variable

Required

Description

`ADAPTO_API_URL`

Yes

Base URL for the Adapto Public API — e.g. [`https://public-api.adaptocms.com/v1`](https://public-api.adaptocms.com/v1)

`ADAPTO_API_KEY`

Yes

Your API key, found in the backoffice under Developer Tools → API Keys

`DEV`

No

Set to `true` to enable verbose request logging (cache hits, misses, retries) in the console

## 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

Method

Parameters

Returns

`list(options)`

`language?`, `status?`, `page?`, `limit?`, `category?`, `tag?`, `keyword?`

`IPaginatedResponse<IArticlePreview>`

`get(id)`

`id: string`

`IArticle`

`getBySlug(slug)`

`slug: string`

`IArticle`

`listAll(options)`

`language?`, `status?`

`IArticle[]`

### adapto.categories

Method

Parameters

Returns

`list(options)`

`language?`, `page?`, `limit?`, `keyword?`

`IPaginatedResponse<ICategory>`

`get(id)`

`id: string`

`ICategory`

`getBySlug(slug)`

`slug: string`

`ICategory`

`getSubcategories(id)`

`id: string`

`ICategory[]`

`listAll(options)`

`language?`

`ICategory[]`

### adapto.pages

Method

Parameters

Returns

`list(options)`

`language?`, `status?`, `page?`, `limit?`

`IPaginatedResponse<IPagePreview>`

`get(id)`

`id: string`

`IPage`

`getBySlug(slug)`

`slug: string`

`IPage`

`listAll(options)`

`language?`, `status?`

`IPage[]`

### adapto.collections

Method

Parameters

Returns

`list(options)`

`language?`, `page?`, `limit?`

`IPaginatedResponse<ICustomCollection>`

`get(id)`

`id: string`

`ICustomCollection`

`getBySlug(slug)`

`slug: string`

`ICustomCollection`

`listAll(options)`

`language?`

`ICustomCollection[]`

`listItems(id, options)`

`id: string`, `language?`, `status?`, `page?`, `limit?`

`IPaginatedResponse<ICustomCollectionItemPreview>`

`getItem(collectionId, itemId)`

`collectionId: string`, `itemId: string`

`ICustomCollectionItem`

`getItemBySlug(collectionId, slug)`

`collectionId: string`, `slug: string`

`ICustomCollectionItem`

`listAllItems(collectionId)`

`collectionId: string`

`ICustomCollectionItem[]`

### adapto.microCopy

Method

Parameters

Returns

`list()`

—

`IMicroCopy[]`

`getByKey(key)`

`key: string`

`IMicroCopy`

`getDictionary(language)`

`language: string`

`Record<string, string>`

### adapto.languages

Method

Parameters

Returns

`list()`

—

`string[]`

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:

Type

Output

`image`

`<img>` with `src`, `alt`, and optional `caption`

`video`

`<video>` element with source URL

`audio`

`<audio>` element with source URL

`document`

Download link to the file URL

`youtube`

`<iframe>` embed

`vimeo`

`<iframe>` embed

`tiktok`

`<iframe>` embed

`instagram_reel`, `instagram_post`

`<iframe>` embed

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