Integration Guide

Step by step: from an editor picking an asset in your platform to a published, transformable CDN URL - and how to keep it in sync over the asset's lifetime.

0. Prerequisites

1. Resolve the DAM source coordinates

The CDN API publishes assets that already live in the Mediaflow DAM. Each asset needs:

• imageId - the alphanumeric Mediaflow mediaId (NOT the numeric file id). Resolve via GET /1/file/{numericFileId}?fields=mediaId,filename,type. Values shorter than 9 characters are rejected with 400 - a numeric file id never passes.

• filename - the original filename, used as the last path segment of the public CDN URL.

• filetype - the Mediaflow file type code, returned as type.id when type is in fields (see Supported file types). Without type the response has no file type.

serverId is sourced server-side from the auth token's serv claim - the integration doesn't pass it in. Integrations typically present a Mediaflow asset picker UI to editors; the picker returns the numeric file id. Resolve mediaId and filename via the file endpoint, and you have everything you need.

2. POST - server-side dedup

POST /1/cdn/resources is idempotent on the natural key (customer, imageId, serverId, cdnId, filename). A repeat call returns the existing resource:

• 200 OK - match on a completed resource. URL and resourceId returned; no work queued.

• 202 Accepted - new resource, or match on registered / error / deleted (re-queued).

A different filename or cdnId is a different resource - that's how you publish the same DAM source as a separate URL. defaults and filetype from the request body are not applied on a dedup hit; use PATCH /defaults to change defaults.

3. Create the CDN resource

POST /1/cdn/resources

{
  "cdnId": 2,
  "source": "mediaflow",
  "metadata": {
    "imageId": "7QX4K2M9PA",
    "filename": "hero.jpg",
    "filetype": 101,
    "defaults": { "width": 1600, "format": "webp", "quality": 85 }
  }
}

The legacy flat body (top-level imageId/filename/filetype/defaults, no source/metadata) is still accepted and treated as source: mediaflow - existing integrations keep working; use the source/metadata shape for new code.

Response - 202 Accepted for a new resource, 200 OK for a dedup hit on a completed one:

{
  "resourceId": "x8k2m4n6p0q3r5s7t9v1wa",
  "status": "registered",
  "url": "https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg",
  "versionedUrl": "https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/v1/hero.jpg"
}

The URL is immediately usable for embedding. New resources transition registered → completed asynchronously; until processing finishes, the edge returns 503 with Retry-After: 30 for the URL - honor the header and retry, or poll the resource for a ready signal.

Need a hard ready signal? Poll GET /1/cdn/resources/{resourceId} until status: completed. Otherwise just return the URL - pages render once processing finishes.

4. Store on the partner platform

Persist two values on the partner platform's record:

• url - what you embed in pages, srcsets, app screens. Stable across source replaces; browsers revalidate it hourly, so a replaced image shows up within the hour without any change on your side.

• resourceId - what you use to call PUT/PATCH/DELETE for the rest of the resource's life.

Only if your platform re-fetches URLs from the API on every build (static-site generators, e-commerce catalogs synced via API) should you store versionedUrl instead of url - see Stable vs versioned URL.

5. Render with transform parameters

The CDN URL works as-is and applies the resource's defaults. To render variants per breakpoint, format, density, etc., append transform parameters - query-style or path-style:

<picture>
  <source type="image/avif"
    srcset="
      https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg?w=400&f=avif  400w,
      https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg?w=800&f=avif  800w,
      https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg?w=1600&f=avif 1600w">
  <source type="image/webp"
    srcset="
      https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg?w=400&f=webp  400w,
      https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg?w=800&f=webp  800w,
      https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg?w=1600&f=webp 1600w">
  <img src="https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg?w=1600&f=jpeg"
       sizes="100vw" alt="…">
</picture>

See Transform parameters for the full list. Query parameters take precedence over path parameters, which take precedence over the resource defaults.

6. Handle updates

URL is unchanged in both cases; the version bumps, the edge cache is purged and cached derivatives invalidate automatically. Browsers that already hold the old image pick the new one up within an hour (see Stable vs versioned URL).

7. Handle deletion

When the asset is removed in the partner platform, call:

DELETE /1/cdn/resources/{resourceId}

Soft-delete; returns 204. A second DELETE on the same resourceId also returns 204 (idempotent). The edge stops serving (404) and the edge cache is purged. Skipping this leaves orphan resources behind.

8. Handle errors