Skip to content
FilmFetch
Docs
Sign in

FilmFetch Public API

Create uploads, follow their status and QC result, manage titles, collections and downloads, fetch the CPL of a DCP, and subscribe to signed webhooks. This page is the guide; the full, always-current endpoint reference is generated from the OpenAPI document.

Version 2.0
OpenAPI 3.1
API key auth

Overview

Interactive endpoint reference

Every operation with its parameters, schemas, example payloads and a try-it console, generated from the OpenAPI document at developers.filmfetch.net.

All paths on this page are relative to the production base URL. There is one environment.

Environment Base URL
Production https://api.filmfetch.net
OpenAPI document v2-specs.yaml

Authentication

Every request carries your API key in the apikey request header. There is no OAuth flow and no bearer token.

bash 
curl https://api.filmfetch.net/v2/uploader-configurations \
  -H "apikey: <your-api-key>"
Keys are scoped to one account
A key only ever sees its own data. Keys are provisioned by FilmFetch, so keep them server-side and never ship one in a browser or mobile client. Need a key? Mail support@filmfetch.net.

The upload flow

Uploading is the entry point of the delivery chain. Five steps from configuration to finished asset.

1

Pick an upload configuration

GET /v2/uploader-configurations returns the configurations available to you, for example DCP, VOD or VOD (DRM). The configuration decides which files may be uploaded and how many.

2

Create the upload

POST /v2/upload with the chosen uploaderId and your own externalId. That external id is echoed back on every status response and webhook, so use it to correlate with your own records.

3

Send the end user to the upload page

Open https://transfer.medialoc.eu/{uploadId} with the id from step 2. The actual file or DCP is transferred there, not through the API.

4

Follow the status

Poll GET /v2/upload/{id} for status, qcStatus and percentage, or skip the polling and subscribe to webhooks.

5

Fetch the result

For a DCP, retrieve the full Composition Playlist as XML via GET /v2/media-assets/cpl/{cplFileId}.

Endpoints

Twenty-two operations across seven groups. Each group links straight into the interactive reference.

Uploads

Full reference

Create uploads from an upload configuration and follow their status and QC result. An upload is the entry point of the delivery flow.

GET /v2/upload/{uploadId}
GET /v2/upload
POST /v2/upload
GET /v2/uploader-configurations

Downloads

Full reference

Search and create downloads for delivery to transfer endpoints.

GET /v2/download
POST /v2/download/media-asset/{mediaAssetId}

Titles

Full reference

Search and manage titles, the catalog entries that uploads and content are linked to.

GET /v2/title
POST /v2/title
GET /v2/title/{titleId}

Collections

Full reference

Operations related to collections.

GET /v2/collection
POST /v2/collection
GET /v2/collection/{collectionId}
POST /v2/collection/{collectionId}/title
DELETE /v2/collection/{collectionId}/title/{titleId}

Media Assets

Full reference

Search media assets and retrieve the Composition Playlist (CPL) of a DCP.

GET /v2/media-asset
GET /v2/media-assets/cpl/{cplFileId}
DELETE /v2/media-asset/{titleId}/{mediaAssetId}

Delivery Points

Full reference

The transfer endpoints (delivery points) configured for your account.

GET /v2/delivery-point

Webhooks

Full reference

Register and manage webhook subscriptions so Filmfetch can notify your endpoint when something happens, instead of you polling. See the Introduction for the full webhook construction and signature verification.

GET /v2/webhooks
POST /v2/webhooks
GET /v2/webhooks/{id}
DELETE /v2/webhooks/{id}

Webhooks

Register a public HTTPS endpoint and FilmFetch POSTs a signed JSON message whenever something happens, so you never have to poll.

1. Register a subscription

bash 
curl -X POST https://api.filmfetch.net/v2/webhooks \
  -H "apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/filmfetch-webhook",
    "eventTypes": ["upload.created", "upload.updated"]
  }'

The response contains a secret that is shown only once. Store it, you need it to verify deliveries.

2. Receive deliveries

Six event types are available: upload.created, upload.updated, upload.deleted and the same three for download. Each delivery carries these headers.

Header Meaning
X-Filmfetch-Event The event type, for example upload.updated.
X-Filmfetch-Delivery Unique delivery id. Deduplicate on this.
X-Filmfetch-Signature sha256=<hex>, the HMAC-SHA256 of the raw body.

3. Verify the signature

Recompute the HMAC over the raw request body with your subscription secret and compare it in constant time.

javascript 
import crypto from "crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

Respond with a 2xx quickly and do the heavy work asynchronously.

Delivery, retries and idempotency

  • A non-2xx response or a timeout counts as failed and is retried with exponential backoff, several attempts over a few hours.
  • The same event may therefore arrive more than once. Deduplicate on X-Filmfetch-Delivery so your processing is idempotent.
  • Target URLs must resolve to a public address. Private, loopback, link-local and cloud-metadata addresses are rejected.

Errors & rate limits

Errors use standard HTTP status codes. Validation problems on the webhook and upload endpoints return a small JSON body with an error code and a human readable message.

Some endpoints are rate limited per account. Exceeding a limit returns 429 Too Many Requests. Back off and retry.

Back to all docs