Skip to main content
The Marble API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

​
Base URL

All API access is over HTTPS and is accessed from the api.marblecms.com domain. All data is sent and received as JSON.
Where :resource is the specific resource you want to interact with (e.g., posts, categories, tags, authors).

​
Authentication

Marble authenticates API requests using API keys. You can create and manage API keys from your workspace dashboard under Settings > API Keys. Include your API key in the Authorization header of every request:
Alternatively, you can pass the API key as a query parameter:

​
API key types and scopes

Every API key carries a set of scopes that determine which resources and operations it can access. The API checks the key’s scopes on every request and returns 403 Forbidden if a required scope is missing. There are two key types:
  • Public keys (mpk_…) can only hold read scopes. They are safe to use from environments where the key may be observed, such as build pipelines for static sites.
  • Private keys (msk_…) can hold any scope, including write scopes and posts_read_drafts. Use them only from trusted server-side environments.
The full list of scopes:
Public API keys are scoped to read operations only, but they should still be handled with care. Exposing your key in client-side code allows anyone to make requests on your behalf, which can lead to your rate limits being exhausted. We recommend using keys on the server-side whenever possible.
Best Practice: Use the Authorization header for all requests. Query parameters may be logged in server access logs.

​
Reading drafts

By default, GET /v1/posts returns only published posts. To include drafts you must:
  1. Use a private API key, and
  2. Grant it the posts_read_drafts scope, and
  3. Pass ?status=draft (drafts only) or ?status=all (drafts + published).
Requests for drafts using a public key, or a private key without posts_read_drafts, return 403 Forbidden.

​
Response Format

All responses are returned as JSON. Successful responses include the requested data, while errors include an error field with details.
All timestamps are in UTC ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

​
Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of a request: Example error response:
When the key is valid but lacks the scope required for the endpoint, the API returns 403 with a message naming the missing scope:
To resolve this, edit the key in Settings > API Keys and grant the missing scope, or use a different key that already has it. Remember that public keys cannot be granted write scopes or posts_read_drafts.