List Documents
Scope required:content:read. Add content:read:draft to include draft documents (when draft=true).
Query Parameters
When
true, only return documents with at least one published version. When
false, only return never-published documents.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.Example
Get Document
Scope required:content:read. Add content:read:draft when using draft=true.
Path Parameters
Query Parameters
Example
Create Preview Token
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
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
Scope required:content:write
Required headers: X-MDCMS-Schema-Hash, X-MDCMS-CSRF-Token (session auth)
Request Body
BCP 47 locale tag. Required for localized types. Defaults to
__mdcms_default__ for non-localized types.Example
Update Document
Scope required:content:write
Required headers: X-MDCMS-Schema-Hash, X-MDCMS-CSRF-Token (session auth)
Path Parameters
Request Body
Updated frontmatter. Partial updates are not supported — provide the complete
frontmatter object.
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
Scope required:content:publish
Path Parameters
Request Body
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
Example request:List Versions
Scope required:content:read
Path Parameters
Query Parameters
Example request:Get Version
Scope required:content:read
Path Parameters
Example request: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
Example request: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
Example request:Restore Deleted Document
Scope required:content:write
Path Parameters
Example request: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
Example request:Overview Stats
Scope required: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
Scope required:content:read
Path Parameters
The document’s UUID. Any locale variant can be used — the server looks up the
translation group automatically.
Change attribution
Content actors are user IDs derived by the server from authentication. Session writes use the signed-in user; API-key writes use the key creator. LegacycreatedBy, updatedBy, and actorId request body fields are accepted and ignored.
Documents expose optional createdOrigin and updatedOrigin fields. Versions
expose optional publishedOrigin. Origins identify the channel (studio,
studio_ai, mcp, api, or system) and credential (session, api_key,
oauth, or system), with optional credential IDs and a declared client name.
Historical rows without origin metadata remain readable.
Content lists, single-document GET responses, and version lists may include a
top-level users map, keyed by the actor user ID, with { name, email } values.
User lookup is best-effort. Clients must handle a missing map or unresolved ID.
The declared client name comes from the optional X-MDCMS-Client header and is
informational, not authenticated identity.