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
Scope required:media:read
Sort direction:
asc or desc. Defaults to desc for uploadedAt and
sizeBytes, and asc for filename.INVALID_QUERY_PARAM.
Example request:
Upload Media
Scope required:media:upload
Content-Type: multipart/form-data
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.
Get Media
Scope required:media:read
Path Parameters
Example request:Delete Media
Scope required:media:delete
Path Parameters
Example request: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
Scope required:webhooks:read
Example request:
Create Webhook
Scope required:webhooks:write
List of event types to subscribe to. See Event Types below.
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.
Update Webhook
Scope required:webhooks:write
Path Parameters
Example request:Delete Webhook
Scope required:webhooks:write
Path Parameters
Example request:Event Types
Webhook Payload
All webhook deliveries use the following envelope:origin is the document’s updatedOrigin from the write that
triggered the event. It is omitted when no change origin is available.
Signature Verification
Every webhook delivery includes anX-MDCMS-Signature header for payload verification:
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) andv1(signature) values from the header. - Construct the signed payload:
{timestamp}.{raw_body}. - Compute
HMAC-SHA256(secret, signed_payload). - Compare the computed digest with the
v1value (use constant-time comparison). - Optionally, reject payloads where the timestamp is more than 5 minutes old to prevent replay attacks.
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.