API Reference

Reference for the CDN management endpoints on https://api.mediaflow.com: request and response shapes, the resource lifecycle, supported file types and error codes.

Management endpoints

All requests use Content-Type: application/json when a body is sent. All operations are scoped to the calling customer; cross-customer access returns 404.

Endpoint summary

All paths are relative to the Management API host - https://api.mediaflow.com. Each endpoint is documented in detail below.

Create a resource

POST /1/cdn/resources

Request body:

Example:

curl -X POST https://api.mediaflow.com/1/cdn/resources \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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 returned immediately. 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.

List resources for a DAM source

GET /1/cdn/resources?imageId={imageId}

Returns the calling customer's non-deleted resources for a given DAM image. imageId is required; serverId is sourced from the auth token. Inventory query - server-side dedup makes pre-POST checks unnecessary.

An image published under several filenames returns one entry each; a repeat POST on the same key reuses its resource and adds none. Entries carry neither the filename nor the defaults - the filename is part of url. What the match implies:

• The match is on the imageId the resource was created with, or the one last set by PUT. After a source replace the resource is listed under the new imageId only.

• imageId is not validated on this call. A value that matches nothing - a numeric file id, or an imageId from before a source replace - returns [], not 400.

• A token for another file server returns [].

• There is no call that lists all of a customer's resources; keep the resourceId from the POST response.

curl "https://api.mediaflow.com/1/cdn/resources?imageId=7QX4K2M9PA" \
  -H "Authorization: Bearer $TOKEN"

Response - 200 OK:

[
  {
    "resourceId": "x8k2m4n6p0q3r5s7t9v1wa",
    "status": "completed",
    "source": "mediaflow",
    "url": "https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg",
    "versionedUrl": "https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/v1/hero.jpg",
    "cdnId": 2,
    "version": 1
  }
]

Get a resource

GET /1/cdn/resources/{resourceId}

Response - 200 OK (same shape as a list entry). While status is error the response also carries error, a short text saying why processing failed; it is cleared when the resource is reset or re-queued. 404 if the resource does not exist, has been deleted, or belongs to a different customer.

{
  "resourceId": "x8k2m4n6p0q3r5s7t9v1wa",
  "status": "error",
  "error": "download failed: http 400",
  "source": "mediaflow",
  "url": "https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg",
  "versionedUrl": "https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/v1/hero.jpg",
  "cdnId": 2,
  "version": 1
}

Replace the resource source

PUT /1/cdn/resources/{resourceId}

Point the same resource URL at a new DAM source file. URL is unchanged. Version increments - the edge cache is purged and cached derivatives invalidate; the resource transitions back to registered for re-processing and the edge answers 503 Retry-After until it is done.

A deleted resource returns 404.

Request body:

{ "imageId": "NEW_IMAGE_ID" }

Response - 202 Accepted:

{ "resourceId": "x8k2m4n6p0q3r5s7t9v1wa", "status": "registered" }

Update default transform parameters

PATCH /1/cdn/resources/{resourceId}/defaults

Replaces the full defaults object (width, height, quality, format, fit, focusX, focusY, background; format accepts only webp, avif, jpeg, png). Version increments and the edge cache is purged, so the new defaults are visible on the next request. URL is unchanged. A deleted resource returns 404.

{
  "width": 2048,
  "height": 0,
  "quality": 90,
  "format": "avif",
  "fit": "cover"
}

Response - 200 OK:

{
  "resourceId": "x8k2m4n6p0q3r5s7t9v1wa",
  "defaults": { "width": 2048, "quality": 90, "format": "avif", "fit": "cover" }
}

Returns 503 when the defaults were saved but a follow-up step failed; retry the call.

Reset or reactivate a resource

PATCH /1/cdn/resources/{resourceId}

Request body:

{ "status": "registered" }

Accepted from the error, registered, and deleted statuses:

• error → registered - re-queue a resource that failed processing.

• registered → registered - idempotent re-publish; useful for retrying after a 503 on POST.

• deleted → registered - reactivation; re-downloads the source from the DAM.

Returns 202 Accepted with { resourceId, status: "registered" }. 409 if the resource is already completed. Clears the error state and re-queues processing.

Delete a resource

DELETE /1/cdn/resources/{resourceId}

Soft-delete. Returns 204; a second DELETE on the same resourceId also returns 204 (idempotent). The resource is excluded from future queries; the edge stops serving (404) and the edge cache is purged.

Resource lifecycle

registered ─▶ completed        (processed asynchronously)
     │
     ╰─▶ error ─(PATCH status=registered)─▶ registered

any state ─▶ deleted   (DELETE - soft-delete)
deleted   ─(PATCH status=registered)─▶ registered   (reactivation - re-downloads source)

Statuses observable via the API: registered, completed, error, deleted. There is no separate processing status - a resource stays registered while it is being processed.

Supported file types

For non-image types, transform parameters are accepted in the URL but ignored - the file is served unchanged. Other document types (Word, PowerPoint, …) and archives are rejected at publish.

Error responses

Authentication errors from the API gateway (401) return JSON: {"status":401,"error":"Unauthorized"}. Errors from the CDN API itself (400, 404, 409, 503, 500) return a plain-text message with the status code. Internal details are logged server-side and not exposed.