List Documents
/api/v1/content
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
Content type to filter by (e.g.,
BlogPost).BCP 47 locale tag. Filters results to a specific locale.
Exact path match (e.g.,
content/blog/hello-world).Filter by the
slug frontmatter field. Requires the type to have a slug
field.When
true, only return documents with at least one published version. When
false, only return never-published documents.When
true, include soft-deleted documents. Defaults to false.When
true, only return documents with draft changes ahead of the published
version.When
true, return draft content instead of the published version. Requires
content:read:draft scope.Reference field name to resolve. Can be repeated for multiple fields (e.g.,
resolve=author&resolve=category). Resolution is one level deep.Number of results per page. Default
20, maximum 100.Number of results to skip. Default
0.Sort field. Accepted values:
createdAt, updatedAt, path. Default
createdAt.Sort direction:
asc or desc. Default desc.Example
Get Document
/api/v1/content/{documentId}
Retrieve a single document by its ID.
content:read. Add content:read:draft when using draft=true.
Path Parameters
The document’s UUID.
Query Parameters
Locale override. If the document is localized, returns the variant for this
locale.
Reference field name to resolve. Can be repeated.
When
true, return the draft version instead of the published version.Example
Create Preview Token
/api/v1/content/{documentId}/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
The document’s UUID.
Request Body
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
/api/v1/content
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
Content type name (e.g.,
BlogPost).Filesystem path for the document (e.g.,
content/blog/my-new-post).BCP 47 locale tag. Required for localized types. Defaults to
__mdcms_default__ for non-localized types.Document format:
md or mdx. Defaults to md.Structured data matching the content type schema.
Markdown or MDX content body. Defaults to empty string.
Example
Update Document
/api/v1/content/{documentId}
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
The document’s UUID.
Request Body
Updated frontmatter. Partial updates are not supported — provide the complete
frontmatter object.
Updated Markdown or MDX body.
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
/api/v1/content/{documentId}/publish
Publish the current draft, creating an immutable version snapshot.
content:publish
Path Parameters
The document’s UUID.
Request Body
Optional summary of changes in this version (e.g., “Fixed typos and updated
pricing section”).
Example
Unpublish Document
/api/v1/content/{documentId}/unpublish
Remove the published version, reverting the document to draft-only state. The
version history is preserved.
content:publish
Path Parameters
The document’s UUID.
List Versions
/api/v1/content/{documentId}/versions
Retrieve the version history of a document. Each entry represents a published
snapshot.
content:read
Path Parameters
The document’s UUID.
Query Parameters
Number of versions per page. Default
20, maximum 100.Number of versions to skip. Default
0.Get Version
/api/v1/content/{documentId}/versions/{version}
Retrieve the full content snapshot of a specific published version.
content:read
Path Parameters
The document’s UUID.
The version number to retrieve.
Restore Version
/api/v1/content/{documentId}/versions/{version}/restore
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
The document’s UUID.
The version number to restore from.
Delete Document
/api/v1/content/{documentId}
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
The document’s UUID.
Restore Deleted Document
/api/v1/content/{documentId}/restore
Restore a soft-deleted document, making it visible in normal queries again.
content:write
Path Parameters
The document’s UUID.
Duplicate Document
/api/v1/content/{documentId}/duplicate
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
The source document’s UUID.
Overview Stats
/api/v1/content/overview
Get aggregate counts of documents per content type. Useful for building
editorial dashboards.
content:read
Query Parameters
Filter to specific types. Can be repeated (e.g.,
type=BlogPost&type=Author).
When omitted, returns counts for all types.Get Variants
/api/v1/content/{documentId}/variants
Returns all locale variants for a document, identified by their shared
translation group.
content:read
Path Parameters
The document’s UUID. Any locale variant can be used — the server looks up the
translation group automatically.