Skip to main content

​
Quick Start

Make your first API request in seconds! Copy and paste this command into your terminal:
Replace YOUR_API_KEY with an API key from your Marble dashboard.

​
Creating an API Key

1

Open your workspace settings

Navigate to your workspace dashboard and click Settings in the sidebar.
2

Go to API Keys

Click on API Keys in the settings menu.
3

Create a new key

Click Create API Key, give it a descriptive name (e.g., “Production Website”), and choose a key type and permissions (see below).
4

Copy your key

Your API key will only be shown once. Copy it and store it securely.

​
Choosing a key type

  • Public key (mpk_…) — read-only. Pick this for client-side code, static site generators, or anywhere the key may be observed. Public keys can only hold the read scopes: posts_read, authors_read, categories_read, tags_read, media_read, and fields_read.
  • Private key (msk_…) — full access. Use it from trusted server-side environments. Private keys can additionally hold write scopes (posts_write, authors_write, categories_write, tags_write, media_write, fields_write) and posts_read_drafts for reading unpublished posts.

​
Choosing permissions

When creating a key, the Permissions section lists every available scope. Grant only the scopes the integration needs — for example, a website that lists published posts and authors needs posts_read and authors_read and nothing else. To read drafts via GET /v1/posts?status=draft or ?status=all, create a private key and include the posts_read_drafts scope; otherwise the request returns 403 Forbidden. See Authentication for the full scope reference and the 403 "API key missing required scope: <scope>" response.
API keys should be kept secure. Public keys are scoped to read operations only, but exposing them in client-side code can lead to your rate limits being consumed by others. Never ship a private key to the client — it can write to your workspace and read drafts. We recommend performing API requests on the server-side whenever possible.

​
Authentication

Include your API key in the Authorization header:
Alternatively, use the key query parameter:
The Authorization header method is recommended for security. Query parameters may appear in server logs.

​
Available Resources

  • Posts: List, get, create, update, or delete posts
  • Authors: List, get, create, update, or delete authors
  • Categories: List, get, create, update, or delete categories
  • Tags: List, get, create, update, or delete tags
  • Media: List, get, upload, update, or delete media assets

​
Next Steps

Pagination

Learn how to paginate through large result sets.

Rate Limits

Understand API rate limiting and best practices.

TypeScript Types

Use our TypeScript definitions for type-safe development.