Skip to main content
The Content API provides full lifecycle management for documents: creation, querying, editing, publishing, versioning, deletion, and restoration. All content endpoints require the standard authentication headers.

List Documents

Retrieve a paginated list of documents, filtered by type and optional criteria.
Scope required: content:read. Add content:read:draft to include draft documents (when draft=true).

Query Parameters

string
required
Content type to filter by (e.g., BlogPost).
string
BCP 47 locale tag. Filters results to a specific locale.
string
Exact path match (e.g., content/blog/hello-world).
string
Filter by the slug frontmatter field. Requires the type to have a slug field.
boolean
When true, only return documents with at least one published version. When false, only return never-published documents.
boolean
When true, include soft-deleted documents. Defaults to false.
boolean
When true, only return documents with draft changes ahead of the published version.
boolean
When true, return draft content instead of the published version. Requires content:read:draft scope.
string
Reference field name to resolve. Can be repeated for multiple fields (e.g., resolve=author&resolve=category). Resolution is one level deep.
integer
Number of results per page. Default 20, maximum 100.
integer
Number of results to skip. Default 0.
string
Sort field. Accepted values: createdAt, updatedAt, path. Default createdAt.
string
Sort direction: asc or desc. Default desc.

Example

Response:

Get Document

Retrieve a single document by its ID.
Scope required: content:read. Add content:read:draft when using draft=true.

Path Parameters

string
required
The document’s UUID.

Query Parameters

string
Locale override. If the document is localized, returns the variant for this locale.
string
Reference field name to resolve. Can be repeated.
boolean
When true, return the draft version instead of the published version.

Example

Response:

Create Preview Token

Mint a short-lived signed token for a host-app draft preview route.
Scope required: content:read:draft Required headers: X-MDCMS-CSRF-Token (session auth) The token is bound to the persisted draft document, project, environment, locale, path, draft revision, and optional preview URL. It is not an API key. Host routes verify it with @mdcms/sdk before fetching draft: true content.

Path Parameters

string
required
The document’s UUID.

Request Body

string
Host preview URL Studio intends to load. When provided, it is included in the token claims so host routes can bind preview tokens to a route.

Example

cURL
Response:

Errors


Create Document

Create a new document of the specified content type.
Scope required: content:write Required headers: X-MDCMS-Schema-Hash, X-MDCMS-CSRF-Token (session auth)

Request Body

string
required
Content type name (e.g., BlogPost).
string
required
Filesystem path for the document (e.g., content/blog/my-new-post).
string
BCP 47 locale tag. Required for localized types. Defaults to __mdcms_default__ for non-localized types.
string
Document format: md or mdx. Defaults to md.
object
required
Structured data matching the content type schema.
string
Markdown or MDX content body. Defaults to empty string.

Example

Response:
Error cases:

Update Document

Update an existing document’s frontmatter and/or body.
Scope required: content:write Required headers: X-MDCMS-Schema-Hash, X-MDCMS-CSRF-Token (session auth)

Path Parameters

string
required
The document’s UUID.

Request Body

object
Updated frontmatter. Partial updates are not supported — provide the complete frontmatter object.
string
Updated Markdown or MDX body.
integer
required
The draftRevision value from the last fetch. Used for optimistic concurrency control. If the server’s current revision is higher, the update is rejected with a CONFLICT error.

Example

Response:
Error cases:

Publish Document

Publish the current draft, creating an immutable version snapshot.
Scope required: content:publish

Path Parameters

string
required
The document’s UUID.

Request Body

string
Optional summary of changes in this version (e.g., “Fixed typos and updated pricing section”).

Example

Response:

Unpublish Document

Remove the published version, reverting the document to draft-only state. The version history is preserved.
Scope required: content:publish

Path Parameters

string
required
The document’s UUID.
Example request:
Response:

List Versions

Retrieve the version history of a document. Each entry represents a published snapshot.
Scope required: content:read

Path Parameters

string
required
The document’s UUID.

Query Parameters

integer
Number of versions per page. Default 20, maximum 100.
integer
Number of versions to skip. Default 0.
Example request:
Response:

Get Version

Retrieve the full content snapshot of a specific published version.
Scope required: content:read

Path Parameters

string
required
The document’s UUID.
integer
required
The version number to retrieve.
Example request:
Response:

Restore Version

Restore the document’s draft to the state captured in a specific version. This does not delete any version history — it creates a new draft revision with the content from the specified version.
Scope required: content:write

Path Parameters

string
required
The document’s UUID.
integer
required
The version number to restore from.
Example request:
Response:

Delete Document

Soft-delete a document. The document remains in the database but is excluded from normal queries. It can be restored later.
Scope required: content:delete

Path Parameters

string
required
The document’s UUID.
Example request:
Response:

Restore Deleted Document

Restore a soft-deleted document, making it visible in normal queries again.
Scope required: content:write

Path Parameters

string
required
The document’s UUID.
Example request:
Response:

Duplicate Document

Create a copy of a document with a new ID and path. The duplicate starts as a draft with no published version, regardless of the source document’s state.
Scope required: content:write

Path Parameters

string
required
The source document’s UUID.
Example request:
Response:

Overview Stats

Get aggregate counts of documents per content type. Useful for building editorial dashboards.
Scope required: content:read

Query Parameters

string
Filter to specific types. Can be repeated (e.g., type=BlogPost&type=Author). When omitted, returns counts for all types.
Example request:
Response:

Get Variants

Returns all locale variants for a document, identified by their shared translation group.
Scope required: content:read

Path Parameters

string
required
The document’s UUID. Any locale variant can be used — the server looks up the translation group automatically.
Example request:
Response:
Non-localized types return a single-element array with the __mdcms_default__ locale.