We recommend using the TypeScript SDK for the best
developer experience. The SDK is fully type-safe and exports all up-to-date
types automatically.
fetch directly and need type definitions, you can import them from the SDK or copy the definitions below.
Importing from the SDK
The@usemarble/sdk package exports all TypeScript types:
npm install @usemarble/sdk
pnpm add @usemarble/sdk
yarn add @usemarble/sdk
bun add @usemarble/sdk
import type { Post, Category, Tag, Author, Pagination } from "@usemarble/sdk";
// Use with fetch
const response = await fetch("https://api.marblecms.com/v1/posts", {
headers: { Authorization: process.env.MARBLE_API_KEY },
});
const data: { posts: Post[]; pagination: Pagination } = await response.json();
Type Definitions
If you prefer to copy the types directly into your project, here are the complete type definitions:export type Post = {
id: string;
slug: string;
title: string;
status: "published" | "draft";
content: string;
featured: boolean;
description: string;
coverImage: string | null;
publishedAt: Date;
updatedAt: Date;
authors: Author[];
category: Omit<Category, "count">;
tags: Omit<Tag, "count">[];
// Custom field values, keyed by field key
fields: Record<string, string | number | boolean | string[] | null>;
};
export type Pagination = {
limit: number;
currentPage: number;
nextPage: number | null;
previousPage: number | null;
totalItems: number;
totalPages: number;
};
export type MarblePostListResponse = {
posts: Post[];
pagination: Pagination;
};
export type MarblePostResponse = {
post: Post;
};
export type Tag = {
id: string;
name: string;
slug: string;
description: string | null;
count: {
posts: number;
};
};
export type MarbleTagResponse = {
tag: Tag;
};
export type MarbleTagListResponse = {
tags: Tag[];
pagination: Pagination;
};
export type Category = {
id: string;
name: string;
slug: string;
description: string | null;
count: {
posts: number;
};
};
export type MarbleCategoryResponse = {
category: Category;
};
export type MarbleCategoryListResponse = {
categories: Category[];
pagination: Pagination;
};
export type Author = {
id: string;
name: string;
slug: string;
image: string | null;
bio: string | null;
role: string | null;
socials: Social[];
// Present on list/detail endpoints, omitted when embedded in a post
count?: {
posts: number;
};
};
export type Social = {
url: string;
platform: SocialPlatform;
};
export type SocialPlatform =
| "x"
| "twitter"
| "github"
| "facebook"
| "instagram"
| "youtube"
| "tiktok"
| "linkedin"
| "website"
| "onlyfans"
| "discord"
| "bluesky";
export type MarbleAuthorResponse = {
author: Author;
};
export type MarbleAuthorListResponse = {
authors: Author[];
pagination: Pagination;
};
Copy these type definitions into a
types/marble.ts file in your project. If
you prefer a published package, use the official SDK that exports these types.NPM package
The official@usemarble/sdk package exports all TypeScript types shown on this page. Installing the package avoids copying the type definitions into multiple projects.
To install the package run:
npm install @usemarble/sdk
yarn add @usemarble/sdk
pnpm add @usemarble/sdk
bun add @usemarble/sdk
import type { Post, Category, Tag, Author } from "@usemarble/sdk";
Zod Schemas
For runtime validation, you can also create Zod schemas for your data:import { z } from "zod";
const PostSchema = z.object({
id: z.string(),
slug: z.string(),
title: z.string(),
status: z.enum(["published", "draft"]),
content: z.string(),
featured: z.boolean(),
description: z.string(),
coverImage: z.string().url().nullable(),
publishedAt: z.coerce.date(),
updatedAt: z.coerce.date(),
authors: z.array(
z.object({
id: z.string(),
name: z.string(),
slug: z.string(),
image: z.string().nullable(),
bio: z.string().nullable(),
role: z.string().nullable(),
socials: z.array(SocialSchema),
})
),
category: z.object({
id: z.string(),
slug: z.string(),
name: z.string(),
description: z.string().nullable(),
}),
tags: z.array(
z.object({
id: z.string(),
slug: z.string(),
name: z.string(),
description: z.string().nullable(),
})
),
fields: z.record(
z.string(),
z.union([
z.string(),
z.number(),
z.boolean(),
z.array(z.string()),
z.null(),
])
),
});
const PaginationSchema = z.object({
limit: z.number(),
currentPage: z.number(),
nextPage: z.number().nullable(),
previousPage: z.number().nullable(),
totalItems: z.number(),
totalPages: z.number(),
});
export const SocialSchema = z.object({
url: z.string(),
platform: SocialPlatformSchema,
});
export const SocialPlatformSchema = z.enum([
"x",
"twitter",
"github",
"facebook",
"instagram",
"youtube",
"tiktok",
"linkedin",
"website",
"onlyfans",
"discord",
"bluesky",
]);