Media & Webhooks

Media API

The Media API uploads, lists, reads, and deletes project-scoped media assets. Media files are stored in S3-compatible object storage, and each request is routed to an explicit project and environment target. All /api/v1/media* endpoints require X-MDCMS-Project and X-MDCMS-Environment headers.

List Media

List media metadata for the routed project and environment.

Scope required: media:read

string

Case-insensitive filename search. Blank strings are ignored.

string

Filter by derived category: image, video, audio, document, archive, or other.

string

Filter by the uploading user ID.

string

Include assets uploaded on or after this YYYY-MM-DD date.

string

Include assets uploaded through this YYYY-MM-DD date.

string

Sort by uploadedAt, filename, or sizeBytes. Defaults to uploadedAt.

string

Sort direction: asc or desc. Defaults to desc for uploadedAt and sizeBytes, and asc for filename.

number

Page size from 1 to 100. Defaults to 30.

number

Zero-based page offset. Defaults to 0.

Duplicate query parameters, unknown query parameters, invalid dates, and inverted date ranges return INVALID_QUERY_PARAM. Example request:

curl "https://cms.example.com/api/v1/media?category=image&q=hero&sort=uploadedAt&order=desc&limit=30&offset=0" \
  -H "X-MDCMS-Project: marketing-site" \
  -H "X-MDCMS-Environment: production" \
  -H "Authorization: Bearer mdcms_key_live_abc123"

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "project": "marketing-site",
      "filename": "hero.png",
      "mimeType": "image/png",
      "sizeBytes": 245760,
      "url": "https://cdn.example.com/marketing-site/media/550e8400-e29b-41d4-a716-446655440000/hero.png",
      "uploadedBy": "880e8400-e29b-41d4-a716-446655440002",
      "uploadedAt": "2026-01-20T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 30,
    "offset": 0,
    "total": 1,
    "hasMore": false
  }
}

Upload Media

Upload a file. The request must use multipart/form-data encoding.

Scope required: media:upload Content-Type: multipart/form-data

file

required

The file to upload. Image uploads are limited by the routed project’s media image upload setting when configured. Non-image uploads are not subject to that image limit.

Example request:

curl -X POST "https://cms.example.com/api/v1/media/upload" \
  -H "X-MDCMS-Project: marketing-site" \
  -H "X-MDCMS-Environment: production" \
  -H "Authorization: Bearer mdcms_key_live_abc123" \
  -F "file=@/path/to/image.png"

Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "project": "marketing-site",
    "filename": "image.png",
    "mimeType": "image/png",
    "sizeBytes": 245760,
    "url": "https://cdn.example.com/marketing-site/media/550e8400-e29b-41d4-a716-446655440000/image.png",
    "uploadedBy": "880e8400-e29b-41d4-a716-446655440002",
    "uploadedAt": "2026-01-20T10:00:00.000Z"
  }
}

Get Media

Read metadata for one media asset in the routed project and environment.

Scope required: media:read

Path Parameters

string

required

The media asset ID.

Example request:

curl "https://cms.example.com/api/v1/media/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-MDCMS-Project: marketing-site" \
  -H "X-MDCMS-Environment: production" \
  -H "Authorization: Bearer mdcms_key_live_abc123"

Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "project": "marketing-site",
    "filename": "image.png",
    "mimeType": "image/png",
    "sizeBytes": 245760,
    "url": "https://cdn.example.com/marketing-site/media/550e8400-e29b-41d4-a716-446655440000/image.png",
    "uploadedBy": "880e8400-e29b-41d4-a716-446655440002",
    "uploadedAt": "2026-01-20T10:00:00.000Z"
  }
}

Delete Media

Delete a media file. This removes the file from storage and invalidates all URLs.

Scope required: media:delete

Path Parameters

string

required

The media asset ID.

Example request:

curl -X DELETE "https://cms.example.com/api/v1/media/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-MDCMS-Project: marketing-site" \
  -H "X-MDCMS-Environment: production" \
  -H "X-MDCMS-CSRF-Token: csrf_token_value" \
  -H "Authorization: Bearer mdcms_key_live_abc123"

Response:

{
  "data": {
    "deleted": true,
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Media deletion is permanent and cannot be undone. Ensure no documents reference the file before deleting. The API does not scan or rewrite content references.

Webhooks API

Webhooks let you receive real-time HTTP notifications when content changes occur in your project. Configure webhook endpoints to trigger builds, invalidate caches, or sync data with external systems.

The Webhooks API is a post-MVP feature. The endpoints are defined and will be available in an upcoming release.

List Webhooks

Returns all webhook configurations for the current project.

Scope required: webhooks:read Example request:

curl "https://cms.example.com/api/v1/webhooks" \
  -H "X-MDCMS-Project: marketing-site" \
  -H "X-MDCMS-Environment: production" \
  -H "Authorization: Bearer mdcms_key_live_abc123"

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "project": "marketing-site",
      "environment": "production",
      "url": "https://api.example.com/webhooks/mdcms",
      "events": ["content.published", "content.unpublished"],
      "active": true,
      "createdBy": "user_01HZX9N8Y6M2J4K7V3P6Q8R9SA",
      "updatedBy": "user_01HZX9N8Y6M2J4K7V3P6Q8R9SA",
      "createdAt": "2026-01-10T12:00:00.000Z",
      "updatedAt": "2026-01-10T12:00:00.000Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "project": "marketing-site",
      "environment": "production",
      "url": "https://deploy.example.com/trigger",
      "events": ["content.published"],
      "active": true,
      "createdBy": "user_01HZX9N8Y6M2J4K7V3P6Q8R9SA",
      "updatedBy": "user_01HZX9N8Y6M2J4K7V3P6Q8R9SA",
      "createdAt": "2026-01-12T08:00:00.000Z",
      "updatedAt": "2026-01-12T08:00:00.000Z"
    }
  ]
}

Create Webhook

Scope required: webhooks:write

string

required

The HTTPS URL to receive webhook payloads. Must use HTTPS.

string[]

required

List of event types to subscribe to. See Event Types below.

string

required

Shared signing secret for HMAC signature verification. Must be 32 to 4096 characters. Studio generates this value automatically for new webhooks; API clients must provide a cryptographically random value.

boolean

Whether the webhook is active. Defaults to true.

Example request:

curl -X POST "https://cms.example.com/api/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-MDCMS-Project: marketing-site" \
  -H "X-MDCMS-Environment: production" \
  -H "X-MDCMS-CSRF-Token: csrf_token_value" \
  -H "Authorization: Bearer mdcms_key_live_abc123" \
  -d '{
    "url": "https://api.example.com/webhooks/mdcms",
    "events": ["content.published", "content.unpublished", "content.deleted"],
    "secret": "whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "active": true
  }'

Response:

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "project": "marketing-site",
    "environment": "production",
    "url": "https://api.example.com/webhooks/mdcms",
    "events": ["content.published", "content.unpublished", "content.deleted"],
    "active": true,
    "createdBy": "user_01HZX9N8Y6M2J4K7V3P6Q8R9SA",
    "updatedBy": "user_01HZX9N8Y6M2J4K7V3P6Q8R9SA",
    "createdAt": "2026-01-20T10:00:00.000Z",
    "updatedAt": "2026-01-20T10:00:00.000Z"
  }
}

Update Webhook

Update an existing webhook configuration.

Scope required: webhooks:write

Path Parameters

string

required

The webhook ID.

string

Updated HTTPS URL.

string[]

Updated event subscriptions.

string

Updated shared signing secret. Omit this field to preserve the existing write-only secret.

boolean

Enable or disable the webhook.

Example request:

curl -X PUT "https://cms.example.com/api/v1/webhooks/770e8400-e29b-41d4-a716-446655440002" \
  -H "Content-Type: application/json" \
  -H "X-MDCMS-Project: marketing-site" \
  -H "X-MDCMS-Environment: production" \
  -H "X-MDCMS-CSRF-Token: csrf_token_value" \
  -H "Authorization: Bearer mdcms_key_live_abc123" \
  -d '{
    "events": ["content.published", "content.unpublished", "content.deleted", "content.created"],
    "active": true
  }'

Response:

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "project": "marketing-site",
    "environment": "production",
    "url": "https://api.example.com/webhooks/mdcms",
    "events": [
      "content.published",
      "content.unpublished",
      "content.deleted",
      "content.created"
    ],
    "active": true,
    "createdBy": "user_01HZX9N8Y6M2J4K7V3P6Q8R9SA",
    "updatedBy": "user_01HZX9N8Y6M2J4K7V3P6Q8R9SA",
    "createdAt": "2026-01-20T10:00:00.000Z",
    "updatedAt": "2026-01-20T11:00:00.000Z"
  }
}

Delete Webhook

Remove a webhook configuration. Pending deliveries are cancelled.

Scope required: webhooks:write

Path Parameters

string

required

The webhook ID.

Example request:

curl -X DELETE "https://cms.example.com/api/v1/webhooks/770e8400-e29b-41d4-a716-446655440002" \
  -H "X-MDCMS-Project: marketing-site" \
  -H "X-MDCMS-Environment: production" \
  -H "X-MDCMS-CSRF-Token: csrf_token_value" \
  -H "Authorization: Bearer mdcms_key_live_abc123"

Response:

{
  "data": {
    "deleted": true,
    "id": "770e8400-e29b-41d4-a716-446655440002"
  }
}

Event Types

Event	Trigger
`content.created`	A new document is created.
`content.updated`	A document’s draft is updated (frontmatter or body change).
`content.published`	A document is published, creating a new version.
`content.unpublished`	A published document is unpublished.
`content.deleted`	A document is soft-deleted.
`content.restored`	A soft-deleted document is restored.
`media.uploaded`	A media file is uploaded.

Webhook Payload

All webhook deliveries use the following envelope:

{
  "event": "content.published",
  "timestamp": "2026-01-20T12:00:00.000Z",
  "project": "marketing-site",
  "environment": "production",
  "document": {
    "documentId": "550e8400-e29b-41d4-a716-446655440000",
    "translationGroupId": "660e8400-e29b-41d4-a716-446655440001",
    "type": "BlogPost",
    "path": "content/blog/hello-world",
    "locale": "en",
    "format": "mdx",
    "version": 4
  },
  "user": {
    "id": "user_01HZX9N8Y6M2J4K7V3P6Q8R9SA",
    "email": "editor@example.com"
  }
}

Signature Verification

Every webhook delivery includes an X-MDCMS-Signature header for payload verification:

X-MDCMS-Signature: t=1705747200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

The signature is an HMAC-SHA256 digest computed over the concatenation of the timestamp and the raw request body, using the webhook’s secret as the key. The raw body must be the exact bytes MDCMS sent; parsing JSON and serializing it again can change whitespace or key order and invalidate the signature. Verification algorithm:

Extract the t (timestamp) and v1 (signature) values from the header.
Construct the signed payload: {timestamp}.{raw_body}.
Compute HMAC-SHA256(secret, signed_payload).
Compare the computed digest with the v1 value (use constant-time comparison).
Optionally, reject payloads where the timestamp is more than 5 minutes old to prevent replay attacks.

Verification helper (Node.js):

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhookSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
  toleranceSeconds = 300,
): boolean {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => {
      const [key, value] = p.split("=");
      return [key, value];
    }),
  );

  const timestamp = parts.t;
  const signature = parts.v1;

  if (!timestamp || !signature) {
    return false;
  }

  const timestampSeconds = Number.parseInt(timestamp, 10);
  if (!Number.isSafeInteger(timestampSeconds) || timestampSeconds < 0) {
    return false;
  }

  const age = Math.abs(Math.floor(Date.now() / 1000) - timestampSeconds);
  if (age > toleranceSeconds) {
    return false;
  }

  const signedPayload = `${timestamp}.${rawBody}`;
  const expected = createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");
  const actualBuffer = Buffer.from(signature, "hex");
  const expectedBuffer = Buffer.from(expected, "hex");

  if (actualBuffer.length !== expectedBuffer.length) {
    return false;
  }

  return timingSafeEqual(actualBuffer, expectedBuffer);
}

Express receiver example:

import express from "express";

const app = express();
const signingSecret = process.env.MDCMS_WEBHOOK_SIGNING_SECRET!;

app.post(
  "/webhooks/mdcms",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const rawBody = req.body.toString("utf8");
    const signature = req.header("x-mdcms-signature");

    if (!verifyWebhookSignature(rawBody, signature ?? "", signingSecret)) {
      res.status(401).send("Invalid webhook signature");
      return;
    }

    const payload = JSON.parse(rawBody);

    // Process the verified payload asynchronously if work may take longer than
    // a few seconds.
    queueWebhookJob(payload);
    res.sendStatus(200);
  },
);

Delivery Behavior

Async delivery — Webhooks are dispatched asynchronously and do not block the originating API request.
Retries — Failed deliveries (non-2xx responses or network errors) use three total attempts: the initial attempt, then retries after 1 second and 2 seconds.
HTTPS only — Webhook URLs must use HTTPS. HTTP URLs are rejected at configuration time.
Timeout — Each delivery attempt has a 10-second timeout. If the endpoint does not respond within 10 seconds, the attempt is marked as failed.

Return a 200 status code as quickly as possible from your webhook endpoint. Perform any heavy processing asynchronously to avoid timeouts.

Getting Started

Endpoints

SDK

Media & Webhooks

Media API

List Media

Upload Media

Get Media

Path Parameters

Delete Media

Path Parameters

Webhooks API

List Webhooks

Create Webhook

Update Webhook

Path Parameters

Delete Webhook

Path Parameters

Event Types

Webhook Payload

Signature Verification

Delivery Behavior

​Media API

​List Media

​Upload Media

​Get Media

​Path Parameters

​Delete Media

​Path Parameters

​Webhooks API

​List Webhooks

​Create Webhook

​Update Webhook

​Path Parameters

​Delete Webhook

​Path Parameters

​Event Types

​Webhook Payload

​Signature Verification

​Delivery Behavior

Media API

List Media

Upload Media

Get Media

Path Parameters

Delete Media

Path Parameters

Webhooks API

List Webhooks

Create Webhook

Update Webhook

Path Parameters

Delete Webhook

Path Parameters

Event Types

Webhook Payload

Signature Verification

Delivery Behavior