> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marblecms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Marble TypeScript SDK

> Official Marble TypeScript SDK with full type safety, automatic retries, pagination helpers, and framework-agnostic access to your workspace content.

Developer-friendly & type-safe TypeScript SDK for the Marble API. Built with automatic retries, pagination helpers, and full TypeScript support.

## Installation

```bash npm theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install @usemarble/sdk
```

```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm add @usemarble/sdk
```

```bash yarn theme={"theme":{"light":"github-light","dark":"github-dark"}}
yarn add @usemarble/sdk
```

```bash bun theme={"theme":{"light":"github-light","dark":"github-dark"}}
bun add @usemarble/sdk
```

> [!NOTE]
>
> This package is published with CommonJS and ES Modules (ESM) support.

## Quick Start

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

async function run() {
  const result = await marble.posts.list({
    limit: 10,
    page: 1,
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();
```

## Authentication

The SDK uses API key authentication. Pass your API key when initializing the client:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});
```

> [!TIP]
>
> Set the `MARBLE_API_KEY` environment variable and the SDK will automatically
> use it.

## Available Resources

> [card] Posts
>
> * List all posts
> * Get a single post

> [card] Categories
>
> * List all categories
> * Get a single category

> [card] Tags
>
> * List all tags
> * Get a single tag

> [card] Authors
>
> * List all authors
> * Get a single author

> [card] Fields
>
> * List custom fields
> * Create and update field definitions
> * Write field values on posts

## Filtering Posts

Filter posts by categories, tags, or featured status:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const result = await marble.posts.list({
  featured: "true",
  categories: "tech,news",
  excludeCategories: "drafts",
  tags: "javascript,react",
  excludeTags: "outdated",
});
```

For a complete guide on filtering options and behavior, see the [Filtering documentation](https://docs.marblecms.com/api/filtering.md).

## Scheduling Posts

Set `status` to `scheduled` and `publishedAt` to a future time. Marble publishes the post within about a minute of that time. This needs a private API key:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const result = await marble.posts.create({
  title: "Launch day",
  content: "<p>We're live.</p>",
  description: "Our launch post",
  slug: "launch-day",
  categoryId: "your-category-id",
  status: "scheduled",
  publishedAt: new Date("2026-11-20T09:00:00Z"),
});
```

Use `posts.update` to change a scheduled post:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Reschedule
await marble.posts.update({
  identifier: "launch-day",
  body: { publishedAt: new Date("2026-11-21T09:00:00Z") },
});

// Publish now
await marble.posts.update({
  identifier: "launch-day",
  body: { status: "published" },
});

// Unschedule, which moves it back to a draft
await marble.posts.update({
  identifier: "launch-day",
  body: { status: "draft" },
});
```

To list scheduled posts, call `posts.list({ status: "scheduled" })`. The default list returns published posts only, and `status: "all"` leaves scheduled posts out.

The SDK's `publishedAt` is a JavaScript `Date`, so it always sends an exact moment in UTC. The workspace-time form in the REST API isn't available here. For the full rules, see [Scheduling a post](https://docs.marblecms.com/concepts/content-model.md#scheduling-a-post).

## Pagination

Paginated endpoints return an async iterable. Use `for await...of` to iterate through pages:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const result = await marble.posts.list({
  limit: 10,
  page: 1,
});

for await (const page of result) {
  console.log(page.posts);
  console.log(page.pagination);
}
```

For full pagination details and response fields, see the [Pagination documentation](https://docs.marblecms.com/api/pagination.md).

## Error Handling

The SDK provides typed error classes for different error scenarios:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Marble } from "@usemarble/sdk";
import * as errors from "@usemarble/sdk/models/errors";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

try {
  const result = await marble.posts.get("non-existent-slug");
} catch (error) {
  if (error instanceof errors.NotFoundError) {
    console.log("Post not found");
  } else if (error instanceof errors.MarbleError) {
    console.log(error.message);
    console.log(error.statusCode);
  }
}
```

## Retries

The SDK automatically retries failed requests. You can customize retry behavior:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});
```

## Framework Guides

> [card] [Astro](https://docs.marblecms.com/integrations/astro.md)
>
> Use Content Collections with Astro.

> [card] [Framer](https://docs.marblecms.com/integrations/framer.md)
>
> Sync content to Framer CMS with the Marble plugin.

> [card] [Next.js](https://docs.marblecms.com/integrations/nextjs.md)
>
> Build static and server-rendered pages.

> [card] [TanStack Start](https://docs.marblecms.com/integrations/tanstack.md)
>
> Server functions with TanStack Start.

## Additional Resources

> [card] [NPM Package](https://www.npmjs.com/package/@usemarble/sdk)
>
> View the package on npm.

> [card] [GitHub](https://github.com/usemarble/marble-ts)
>
> View the source code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.