List Documents
Retrieve a paginated list of documents, filtered by type and optional
criteria.
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
Get Document
Retrieve a single document by its ID.
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
Create Preview Token
Mint a short-lived signed token for a host-app draft preview route.
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
Errors
Create Document
Create a new document of the specified content type.
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
Update Document
Update an existing document’s frontmatter and/or body.
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
Publish Document
Publish the current draft, creating an immutable version snapshot.
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
Unpublish Document
Remove the published version, reverting the document to draft-only state. The
version history is preserved.
content:publish
Path Parameters
string
required
The document’s UUID.
List Versions
Retrieve the version history of a document. Each entry represents a published
snapshot.
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.Get Version
Retrieve the full content snapshot of a specific published version.
content:read
Path Parameters
string
required
The document’s UUID.
integer
required
The version number to retrieve.
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.
content:write
Path Parameters
string
required
The document’s UUID.
integer
required
The version number to restore from.
Delete Document
Soft-delete a document. The document remains in the database but is excluded
from normal queries. It can be restored later.
content:delete
Path Parameters
string
required
The document’s UUID.
Restore Deleted Document
Restore a soft-deleted document, making it visible in normal queries again.
content:write
Path Parameters
string
required
The document’s UUID.
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.
content:write
Path Parameters
string
required
The source document’s UUID.
Overview Stats
Get aggregate counts of documents per content type. Useful for building
editorial dashboards.
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.Get Variants
Returns all locale variants for a document, identified by their shared
translation group.
content:read
Path Parameters
string
required
The document’s UUID. Any locale variant can be used — the server looks up the
translation group automatically.