Content Types API

CRUD operations, filtering, sorting, pagination, file upload, and revision management for any content type.

Use client.collection() to access any content type's data. This works for both custom and built-in content types.

Access a Content Type

const portfolios = client.collection<Portfolio>("portfolios");

// Admin API (bypasses filters, shows private fields)
const adminPortfolios = client.adminCollection<Portfolio>("portfolios");

Read Operations

List with Pagination

const result = await portfolios.getList(1, 20);
// result.items   → Portfolio[]
// result.total   → number (total count)
// result.page    → 1
// result.page_size → 20

List with Options

const result = await portfolios.getList(1, 20, {
  filter: 'status = "published"',
  sort: "-created_at",
  expand: "category,tags",
  search: "rust",
  fields: "title,slug,cover",
});

ListOptions

Option	Type	Description
`filter`	string	Rule engine filter expression
`sort`	string	Sort field. Prefix `-` for DESC (e.g., `"-created_at"`)
`expand`	string	Comma-separated relation fields to populate
`search`	string	Full-text search term
`fields`	string	Comma-separated field whitelist
`status`	string	Filter by status (statusable content types)
`requestKey`	string	Auto-cancels previous request with same key
`headers`	object	Custom request headers
`signal`	AbortSignal	Abort controller signal

Get Single Item

const item = await portfolios.getOne("item_id");

// With options
const item = await portfolios.getOne("item_id", {
  expand: "category,tags",
});

Get by Filter

const item = await portfolios.getFirstListItem('slug = "my-saas"');

Throws SDKError with status 404 if no match.

Get All Items (Auto-Paginate)

const all = await portfolios.getFullList({
  filter: 'status = "published"',
  sort: "-created_at",
});
// all → Portfolio[] (fetches all pages automatically)

Write Operations

Create

const created = await portfolios.create({
  title: "My SaaS App",
  url: "https://mysaas.com",
  tech_stack: ["Rust", "React"],
});

Update

const updated = await portfolios.update(created.id, {
  url: "https://mysaas.app",
  status: "published",
});

Delete

await portfolios.delete(created.id);

Filter Syntax

The filter option uses the same rule engine as the REST API:

// Simple comparison
'status = "published"'

// Multiple conditions
'status = "published" && price > 0'

// OR logic
'status = "published" || featured = true'

// Like match
'title ~ "%rust%"'

// Field is set
'avatar:isset'

// Length check
'tags:length > 0'

See API Reference - Rule Engine for the complete syntax.

Sort Syntax

// Single field
{ sort: "-created_at" }       // DESC
{ sort: "title" }             // ASC

// Multiple fields
{ sort: "status,-created_at" }

Expand Relations

Use expand to populate relation fields with full records instead of IDs:

// Single relation
const result = await portfolios.getList(1, 20, {
  expand: "category",
});
// result.items[0].category → { id, name, ... } instead of "cat_id"

// Multiple relations
const result = await portfolios.getList(1, 20, {
  expand: "category,tags,instructor",
});

File Upload

Attach files to existing records:

const fileInput = document.querySelector<HTMLInputElement>("#cover")!;
const file = fileInput.files![0];

const updated = await portfolios.upload(created.id, file, "cover");

Parameter	Description
`id`	Record ID
`file`	File object
`fileField`	Field name (default: `"file"`)

For standalone file uploads, use client.media.upload(file).

Revisions

Available for content types with the versionable protocol.

List Revisions

const revisions = await portfolios.listRevisions("item_id", 1, 20);
// revisions.items → Revision[]

Get a Revision

const revision = await portfolios.getRevision("item_id", "revision_id");

Restore a Revision

const restored = await portfolios.restoreRevision("item_id", "revision_id");

Diff Two Revisions

const diff = await portfolios.diffRevisions("item_id", "rev_a_id", "rev_b_id");
// diff → { field: { old, new }, ... }

TypeScript

Define Types

interface Portfolio {
  id: string;
  title: string;
  url?: string;
  cover?: string;
  description?: string;
  tech_stack?: string[];
  status: string;
  created_at: string;
  updated_at: string;
}

Use Generics

const portfolios = client.collection<Portfolio>("portfolios");

const item = await portfolios.getOne("abc123");
//    ^? Portfolio

const result = await portfolios.getList(1, 20);
// result.items → Portfolio[]

Generate Types from CLI

raisfast ct types portfolio -o types/portfolio.ts

This generates TypeScript interfaces from the content type TOML definition.

PaginatedData Type

interface PaginatedData<T> {
  items: T[];
  total: number;
  page: number;
  page_size: number;
}

RequestOptions

All methods accept an optional RequestOptions:

interface RequestOptions {
  headers?: Record<string, string>;
  query?: Record<string, string>;
  signal?: AbortSignal;
  requestKey?: string;
  fetch?: typeof fetch;
}

Content Types API

On this page