# Marble Documentation

> Documentation for Marble, the simple headless CMS for writers and developers.

## Docs

- [Create author](https://docs.marblecms.com/api-reference/authors/create-author.md): Create a new author. Requires a private API key. Plan limits apply.
- [Delete author](https://docs.marblecms.com/api-reference/authors/delete-author.md): Delete an author by ID or slug. Requires a private API key.
- [Get author](https://docs.marblecms.com/api-reference/authors/get-author.md): Get a single author by ID or slug
- [List authors](https://docs.marblecms.com/api-reference/authors/list-authors.md): Get a paginated list of authors who have published posts
- [Update author](https://docs.marblecms.com/api-reference/authors/update-author.md): Update an existing author by ID or slug. Requires a private API key.
- [Create category](https://docs.marblecms.com/api-reference/categories/create-category.md): Create a new category. Requires a private API key.
- [Delete category](https://docs.marblecms.com/api-reference/categories/delete-category.md): Delete a category by ID or slug. Requires a private API key. Cannot delete a category that has posts assigned to it.
- [Get category](https://docs.marblecms.com/api-reference/categories/get-category.md): Get a single category by ID or slug
- [List categories](https://docs.marblecms.com/api-reference/categories/list-categories.md): Get a paginated list of categories
- [Update category](https://docs.marblecms.com/api-reference/categories/update-category.md): Update an existing category by ID or slug. Requires a private API key.
- [Delete media asset](https://docs.marblecms.com/api-reference/media/delete-media-asset.md): Delete a media asset and its R2 object. Requires a private API key.
- [Get media asset](https://docs.marblecms.com/api-reference/media/get-media-asset.md): Retrieve a single media asset by ID.
- [List media assets](https://docs.marblecms.com/api-reference/media/list-media-assets.md): Retrieve media assets for the authenticated workspace.
- [Update media asset](https://docs.marblecms.com/api-reference/media/update-media-asset.md): Update media asset metadata. Requires a private API key.
- [Upload media asset](https://docs.marblecms.com/api-reference/media/upload-media-asset.md): Upload a media file and create a media asset. Requires a private API key. Maximum file size is 5 MiB.
- [Create post](https://docs.marblecms.com/api-reference/posts/create-post.md): Create a new post. Requires a private API key. Category is required. If authors are not provided, the first workspace author is used.
- [Delete post](https://docs.marblecms.com/api-reference/posts/delete-post.md): Delete a post by ID or slug. Requires a private API key.
- [Get post](https://docs.marblecms.com/api-reference/posts/get-post.md): Get a single post by ID or slug, with optional status filtering
- [List posts](https://docs.marblecms.com/api-reference/posts/list-posts.md): Get a paginated list of published posts with optional filtering
- [Update post](https://docs.marblecms.com/api-reference/posts/update-post.md): Update an existing post by ID or slug. All fields are optional — only provided fields are updated. Requires a private API key.
- [Create tag](https://docs.marblecms.com/api-reference/tags/create-tag.md): Create a new tag. Requires a private API key.
- [Delete tag](https://docs.marblecms.com/api-reference/tags/delete-tag.md): Delete a tag by ID or slug. Requires a private API key.
- [Get tag](https://docs.marblecms.com/api-reference/tags/get-tag.md): Get a single tag by ID or slug
- [List tags](https://docs.marblecms.com/api-reference/tags/list-tags.md): Get a paginated list of tags
- [Update tag](https://docs.marblecms.com/api-reference/tags/update-tag.md): Update an existing tag by ID or slug. Requires a private API key.
- [Filtering](https://docs.marblecms.com/api/filtering.md): Filter Marble posts by categories, tags, featured status, and search queries with include and exclude semantics, SDK examples, and precedence rules.
- [Marble API Reference](https://docs.marblecms.com/api/introduction.md): Overview of the Marble REST API: base URL, API key authentication, scope-based permissions, JSON response format, and HTTP error codes.
- [Pagination](https://docs.marblecms.com/api/pagination.md): Paginate list endpoints in the Marble API with the limit and page query parameters, response metadata, async iteration, and error handling examples.
- [API Authentication](https://docs.marblecms.com/api/quickstart.md): Create a public or private API key, choose the right scopes, and make your first authenticated request to the Marble REST API in minutes.
- [Rate Limits](https://docs.marblecms.com/api/rate-limits.md): Marble API rate limits, X-RateLimit response headers, 429 error handling, and an exponential backoff pattern to keep clients within per-API-key quotas.
- [TypeScript Types](https://docs.marblecms.com/api/types.md): TypeScript types and Zod schemas for Marble API responses — Post, Author, Category, Tag, Pagination — via the SDK or copy-paste definitions.
- [Content Model](https://docs.marblecms.com/concepts/content-model.md): Marble's content model — how posts relate to authors, a single category, multiple tags, and custom fields, with the fields and JSON shape returned by the API.
- [What Is a Headless CMS?](https://docs.marblecms.com/concepts/headless-cms.md): What a headless CMS is, how it differs from monolithic platforms like WordPress, the benefits for developers, and where Marble fits in the content flow.
- [Workspaces & Teams](https://docs.marblecms.com/concepts/workspaces.md): How Marble workspaces isolate posts, media, API keys, and members, plus Owner, Admin, and Member team roles and the difference between members and authors.
- [Custom Fields](https://docs.marblecms.com/features/custom-fields.md): Extend Marble posts with structured workspace-specific metadata like release dates, priorities, or product names and read them from the API.
- [Marble's Editor](https://docs.marblecms.com/features/editor.md): Marble's distraction-free editor with inline formatting, image and video embeds, metadata sidebar, and Content AI readability scoring and writing suggestions.
- [Exporting Content](https://docs.marblecms.com/features/export.md): Export your workspace as a downloadable JSON archive containing posts, categories, tags, authors, media metadata, custom fields, and a manifest.
- [Importing Content](https://docs.marblecms.com/features/import.md): Bring existing Markdown and MDX files into Marble as draft posts using the queued import workflow, with a syntax compatibility reference.
- [Media & Image Hosting](https://docs.marblecms.com/features/media.md): Upload images, video, audio, and documents to Marble's built-in media library and CDN, then embed them in posts or access them via the REST API and MCP.
- [Webhooks](https://docs.marblecms.com/features/webhooks.md): Configure Marble webhooks to revalidate static sites, automate workflows, verify signatures, and inspect deliveries when content changes.
- [Astro Integration](https://docs.marblecms.com/integrations/astro.md): Integrate Marble with Astro using Content Collections and a custom SDK-powered Content Loader, with typed list pages and dynamic slug routes.
- [Framer Integration](https://docs.marblecms.com/integrations/framer.md): Sync Marble posts into Framer CMS managed collections using the no-code Marble plugin — install, map fields, and re-run to keep content in sync.
- [Next.js Integration](https://docs.marblecms.com/integrations/nextjs.md): Connect Marble to a Next.js App Router project — install the SDK, configure env vars, render dynamic slug routes, and revalidate posts with ISR.
- [TanStack Start Integration](https://docs.marblecms.com/integrations/tanstack.md): Add Marble as a headless CMS to a TanStack Start app — install the SDK, fetch posts in route loaders, and render dynamic slug pages with full type safety.
- [What is Marble](https://docs.marblecms.com/introduction.md): Marble is a simple, open-source headless CMS for writers and developers, with a clean editor, REST API, team collaboration, and built-in image hosting.
- [Set Up Your Workspace](https://docs.marblecms.com/quickstart.md): Get started with Marble in minutes — sign up, create a workspace, explore the dashboard, and publish your first post before wiring it to a frontend.
- [Syntax Highlighting](https://docs.marblecms.com/recipes/code-highlighting.md): Add Shiki-powered syntax highlighting to code blocks in Marble posts, with a reusable highlighter, dual light and dark themes, and SDK integration.
- [Reading Time](https://docs.marblecms.com/recipes/reading-time.md): Calculate and display estimated reading time for Marble posts with a small TypeScript helper that strips HTML and counts words per minute.
- [Marble MCP Server](https://docs.marblecms.com/tools/mcp.md): Connect Claude, Cursor, and other Model Context Protocol clients to your Marble workspace to read, create, and manage content with AI agents.
- [Marble TypeScript SDK](https://docs.marblecms.com/tools/sdk.md): Official Marble TypeScript SDK with full type safety, automatic retries, pagination helpers, and framework-agnostic access to your workspace content.

## OpenAPI Specs

- [openapi](https://api.marblecms.com/openapi.json)

## Optional

- [Blog](https://marblecms.com/blog)
- [Community](https://discord.marblecms.com/)