API Overview

The MDCMS REST API provides programmatic access to all content management operations. This page covers the fundamentals you need to make your first request.

Base URL

All API endpoints are prefixed with:

/api/v1

For a server running at 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:

string

required

The project slug (e.g., marketing-site). Identifies which project the request targets.

string

required

The environment name (e.g., production, staging). Determines which content space the request operates against.

string

required

Authentication credential. Either a Bearer API key (Bearer mdcms_key_<key>) or a session cookie from a browser login.

string

CSRF protection token. Required for all mutation requests (POST, PUT, DELETE) when authenticating via session cookie. Not required for API key authentication.

string

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.

string

Locale override (BCP 47 tag, e.g., en, fr, ja). When set, the server uses this locale instead of the default for the project.

string

Must be application/json for all requests with a JSON body.

Response Envelopes

All API responses follow one of three envelope formats.

Single Resource

Returned by endpoints that fetch or mutate a single entity:

{
  "data": {
    "documentId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "BlogPost",
    "path": "content/blog/hello-world",
    "locale": "en",
    "format": "mdx",
    "frontmatter": {
      "title": "Hello World",
      "slug": "hello-world",
      "publishedAt": "2026-01-15T00:00:00.000Z"
    },
    "body": "Welcome to our blog.",
    "version": 3,
    "publishedVersion": 2,
    "draftRevision": 5,
    "createdAt": "2026-01-10T12:00:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}

Paginated List

Returned by list endpoints:

{
  "data": [
    {
      "documentId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "BlogPost",
      "path": "content/blog/hello-world",
      "frontmatter": {
        "title": "Hello World",
        "slug": "hello-world"
      },
      "version": 3,
      "createdAt": "2026-01-10T12:00:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Error

Returned when a request fails:

{
  "error": {
    "status": "error",
    "code": "NOT_FOUND",
    "message": "Document not found",
    "statusCode": 404,
    "details": {},
    "requestId": "req_abc123def456",
    "timestamp": "2026-01-15T09:30:00.000Z"
  }
}

See the Error Handling page for the full list of error codes.

Pagination

List endpoints accept pagination and sorting parameters:

Parameter	Type	Default	Description
`limit`	integer	`20`	Number of results per page. Maximum `100`.
`offset`	integer	`0`	Number of results to skip.
`sort`	string	`createdAt`	Field to sort by. Accepted values: `createdAt`, `updatedAt`, `path`.
`order`	string	`desc`	Sort direction. Accepted values: `asc`, `desc`.

Example request:

curl "https://cms.example.com/api/v1/content?type=BlogPost&limit=10&offset=20&sort=updatedAt&order=desc" \
  -H "X-MDCMS-Project: marketing-site" \
  -H "X-MDCMS-Environment: production" \
  -H "Authorization: Bearer mdcms_key_live_abc123"

The response includes a pagination object so you can iterate through pages:

{
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 20,
    "hasMore": true
  }
}

When hasMore is true, increment offset by limit to fetch the next page.

Use the @mdcms/sdk package for type-safe access to the API instead of raw HTTP requests. The SDK handles headers, pagination, error parsing, and TypeScript types automatically.

Getting Started

Endpoints

SDK

API Overview

Base URL

Required Headers

Response Envelopes

Single Resource

Paginated List

Error

​Base URL

​Required Headers

​Response Envelopes

​Single Resource

​Paginated List

​Error

​Pagination

Base URL

Required Headers

Response Envelopes

Single Resource

Paginated List

Error

Pagination