Skip to main content
This page provides TypeScript type definitions for all Marble API responses. These types can be used to ensure type safety when integrating Marble with TypeScript projects.
All types are based on the actual API responses and are kept up-to-date with the latest API version.

​
Type Definitions

export type Post = {
  id: string;
  slug: string;
  title: string;
  content: string;
  featured: boolean;
  description: string;
  coverImage: string;
  publishedAt: Date;
  updatedAt: Date;
  authors: Author[];
  category: Omit<Category, "count">;
  tags: Omit<Tag, "count">[];
  attribution: {
    author: string;
    url: 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[];
};

export type Social = {
  url: string;
  platform: SocialPlatform;
};

export type SocialPlatform =
| "x"
| "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, we also provide an official npm package that exports these types .

​
NPM package

We published an official npm package, @usemarble/core, that exports the TypeScript types and zod schemas shown on this page. Installing the package avoids copying the type definitions into multiple projects. To install the package run: 
npm install @usemarble/core
You can import the types like this: 
import { MarblePost } from "@usemarble/core"
The package will be kept up-to-date with the API types and provides a reliable implementation of the webhook signature verification used in our examples.

​
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(),
  content: z.string(),
  featured: z.boolean(),
  description: z.string(),
  coverImage: z.string().url(),
  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(),
  })),
  attribution: z.object({
    author: z.string(),
    url: z.string().url(),
  }).nullable(),
});

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",
  "github", 
  "facebook",
  "instagram",
  "youtube",
  "tiktok",
  "linkedin",
  "website",
  "onlyfans",
  "discord",
  "bluesky"
]);