Base URL
All API endpoints are prefixed with:https://cms.example.com, the full base URL is https://cms.example.com/api/v1.
Required Headers
Every request to the MDCMS API must include the following headers:The project slug (e.g.,
marketing-site). Identifies which project the
request targets.The environment name (e.g.,
production, staging). Determines which content
space the request operates against.Authentication credential. Either a Bearer API key (
Bearer mdcms_key_<key>) or a session cookie from a browser login.CSRF protection token. Required for all mutation requests (POST, PUT, DELETE)
when authenticating via session cookie. Not required for API key
authentication.
Schema hash returned by
mdcms schema sync. Required for content write
operations (create, update) to ensure the client’s schema is in sync with the
server.Locale override (BCP 47 tag, e.g.,
en, fr, ja). When set, the server
uses this locale instead of the default for the project.Optional client name and version, for example
cli/0.4.0. Content writes
record this as the informational declared client name. The server trims
surrounding whitespace and ignores empty values, values containing characters
outside printable ASCII, and values longer than 120 characters. This header
does not establish identity or grant permissions.Response Envelopes
All API responses follow one of three envelope formats.Single Resource
Returned by endpoints that fetch or mutate a single entity:Paginated List
Returned by list endpoints:Error
Returned when a request fails:Pagination
List endpoints accept pagination and sorting parameters:
Example request:
pagination object so you can iterate through pages:
hasMore is true, increment offset by limit to fetch the next page.