openapi: 3.1.0 info: title: Filmfetch Public API version: '2.0' contact: name: Filmfetch Support email: support@filmfetch.net description: "The Filmfetch Public API lets you manage uploads, content and downloads, and\nreceive real-time\ \ webhooks when things happen. This is the V2 contract.\n\n## Base URL\n\n| Environment | Base URL\ \ |\n|-------------|----------|\n| Production | `https://api.filmfetch.net` |\n\nAll paths\ \ below are relative to that base URL.\n\n## Authentication\n\nEvery request must include your API\ \ key in the **`apikey`** request header:\n\n```\napikey: \n```\n\nKeys are provisioned\ \ by Filmfetch and are scoped to a single account, so a\nkey only ever sees its own data. Keep it secret\ \ and server-side.\n\n## Getting started: the upload flow\n\n1. **Pick an upload configuration.**\ \ `GET /v2/uploader-configurations`\n returns the configurations available to you (for example `DCP`,\ \ `VOD`,\n `VOD (DRM)`). A configuration decides which and how many files may be\n uploaded.\n\ 2. **Create an upload.** `POST /v2/upload` with the chosen `uploaderId` and\n your own `externalId`.\ \ The `externalId` is your reference and is echoed\n back on every status response and webhook,\ \ so use it to correlate.\n3. **Send the end user to the upload page.** Open\n `https://transfer.medialoc.eu/{uploadId}`\ \ (the `uploadId` from step 2).\n The actual file or DCP is uploaded there.\n4. **Follow the status.**\ \ Either poll `GET /v2/upload/{id}` for `status`,\n `qcStatus` and `percentage`, or subscribe to\ \ webhooks (below) and be\n notified automatically.\n5. **Fetch the result.** For a DCP you can\ \ retrieve the full Composition\n Playlist (CPL) as XML via `GET /v2/media-assets/cpl/{cplFileId}`.\n\ \n## Webhooks\n\nInstead of polling, register an endpoint and Filmfetch will POST a signed\nJSON message\ \ to it whenever an event occurs. The management operations live\nunder the **Webhooks** tag; the\ \ events we send to you are documented as\nfirst-class **webhook operations** in this reference.\n\ \n### 1. Register a subscription\n\n```bash\ncurl -X POST https://api.filmfetch.net/v2/webhooks\ \ \\\n -H \"apikey: \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \ \ \"url\": \"https://your-app.example.com/filmfetch-webhook\",\n \"eventTypes\": [\"upload.created\"\ , \"upload.updated\"]\n }'\n```\n\nThe `url` must be a **public https endpoint that you host**. The\ \ response\ncontains a `secret` that is shown **only once**, store it, you need it to\nverify deliveries.\n\ \n### 2. Receive deliveries\n\nOn each event we POST the JSON payload to your `url` with these headers:\n\ \n| Header | Meaning |\n|--------|---------|\n| `X-Filmfetch-Event` | The event type, e.g. `upload.updated`.\ \ |\n| `X-Filmfetch-Delivery` | Unique delivery id. Use it to deduplicate. |\n| `X-Filmfetch-Signature`\ \ | `sha256=`, the HMAC-SHA256 of the raw body. |\n\n### 3. Verify the signature\n\nRecompute\ \ the HMAC over the **raw request body** with your subscription\nsecret and compare it (constant time)\ \ to the `X-Filmfetch-Signature` header.\n\n```js\nimport crypto from \"crypto\";\n\nfunction verify(rawBody,\ \ signatureHeader, secret) {\n const expected =\n \"sha256=\" + crypto.createHmac(\"sha256\",\ \ secret).update(rawBody).digest(\"hex\");\n return crypto.timingSafeEqual(\n Buffer.from(signatureHeader),\n\ \ Buffer.from(expected)\n );\n}\n```\n\nRespond quickly with a `2xx`. Do the heavy work asynchronously.\n\ \n### Delivery, retries and idempotency\n\n- A non-2xx response or a timeout counts as failed and\ \ is **retried with\n exponential backoff** (several attempts over a few hours).\n- The same event\ \ may therefore arrive more than once. Deduplicate on\n `X-Filmfetch-Delivery` so your processing\ \ is idempotent.\n- Target URLs must resolve to a public address. Private, loopback,\n link-local\ \ and cloud-metadata addresses are rejected.\n\n## Errors\n\nErrors use standard HTTP status codes.\ \ Validation problems on the webhook\nand upload endpoints return a small JSON body with an `error`\ \ code and a\nhuman readable `message`.\n\n## Rate limits\n\nSome endpoints are rate limited per account.\ \ When you exceed a limit you\nreceive `429 Too Many Requests`; back off and retry.\n" servers: - url: https://api.filmfetch.net description: Production tags: - name: collections description: Operations related to collections. - name: uploads description: 'Create uploads from an upload configuration and follow their status and QC result. An upload is the entry point of the delivery flow.' - name: downloads description: Search and create downloads for delivery to transfer endpoints. - name: titles description: 'Search and manage titles, the catalog entries that uploads and content are linked to.' - name: media assets description: Search media assets and retrieve the Composition Playlist (CPL) of a DCP. - name: delivery points description: The transfer endpoints (delivery points) configured for your account. - name: webhooks description: '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.' components: parameters: WebhookEventHeader: name: X-Filmfetch-Event in: header required: true description: The event type, e.g. upload.updated. schema: type: string WebhookDeliveryHeader: name: X-Filmfetch-Delivery in: header required: true description: Unique delivery id. Deduplicate on this value. schema: type: string WebhookSignatureHeader: name: X-Filmfetch-Signature in: header required: true description: sha256=, the HMAC-SHA256 of the raw request body keyed with your subscription secret. schema: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: apikey description: Every request to the public API must include your API key in a header named "apikey".
Keys are provisioned by Filmfetch and are scoped to your account.

schemas: Error: type: object description: Returned on errors such as an invalid API key, a missing resource, or a validation problem (e.g. an invalid webhook URL or unknown event type). required: - error - message properties: error: type: string description: Machine-readable error code. example: invalid_url message: type: string description: Human-readable explanation of the error. example: Url must use https. WebhookSubscriptionInput: type: object description: Payload to register a new webhook subscription. required: - url - eventTypes properties: url: type: string format: uri description: Public https endpoint that receives the deliveries. Private, loopback, link-local and cloud-metadata addresses are rejected. example: https://your-app.example.com/filmfetch-hook eventTypes: type: array description: The event types this subscription should be notified about. Must contain at least one known event type. items: type: string enum: - upload.created - upload.updated - upload.deleted - download.created - download.updated - download.deleted example: - upload.created - upload.updated description: type: string description: Optional human-readable label for your own reference. example: Production webhook WebhookSubscription: type: object description: A registered webhook subscription. required: - id - url - eventTypes - isActive - created properties: id: type: string description: Unique identifier of the webhook subscription (24-character MongoDB ObjectId). example: 6630a1e2f4b1c9a0d3e4f5a6 url: type: string format: uri description: The public https endpoint that receives the deliveries. example: https://your-app.example.com/filmfetch-hook eventTypes: type: array description: The event types this subscription is notified about. items: type: string enum: - upload.created - upload.updated - upload.deleted - download.created - download.updated - download.deleted example: - upload.created - upload.updated description: type: string nullable: true description: Optional human-readable label provided when the subscription was created. example: Production webhook isActive: type: boolean description: Whether the subscription is currently active and receiving deliveries. example: true created: type: string format: date-time description: Date/time the subscription was created (ISO-8601 UTC). example: '2026-06-12T18:19:16Z' lastDeliveryAt: type: string format: date-time nullable: true description: Date/time of the most recent delivery attempt (ISO-8601 UTC), or null if none has been attempted yet. example: '2026-06-12T18:40:02Z' lastDeliveryStatus: type: string nullable: true description: Outcome of the most recent delivery attempt, or null if none has been attempted yet. example: success secret: type: string nullable: true description: HMAC signing secret used to verify deliveries. Only returned once, in the response to the create call; null on all subsequent reads. example: whsec_3f8a1c2d9b4e6f70a1b2c3d4e5f60718 WebhookEvent: type: object description: The JSON body POSTed to your endpoint on each event. required: - id - event - createdAt - resource properties: id: type: string description: Unique delivery id (also sent as the X-Filmfetch-Delivery header). Use it to deduplicate, since the same event may be delivered more than once. example: 6630a1e2f4b1c9a0d3e4f5a6 event: type: string description: The event type that triggered this delivery. enum: - upload.created - upload.updated - upload.deleted - download.created - download.updated - download.deleted example: upload.created createdAt: type: string format: date-time description: Date/time the event occurred (ISO-8601 UTC). example: '2026-06-12T18:19:16Z' resource: type: object description: Identifies the resource the event is about. required: - type - id properties: type: type: string description: The kind of resource this event concerns. enum: - upload - download example: upload id: type: string description: Id of the affected resource (24-character MongoDB ObjectId). example: 6a2c4da45f00109e85f1b15e customerId: type: string description: Id of the customer the resource belongs to (24-character MongoDB ObjectId). example: 6a2bd5b71b1e7e575738920c data: type: object description: Event-specific fields. For upload events this typically includes uploadStatus and qcStatus; for download events it includes status and changeType. example: uploadStatus: WaitingForUpload qcStatus: None CollectionBasic: type: object description: A lightweight representation of a collection, containing only its identifier and name. required: - Id - Name properties: Id: type: string description: The internal MongoDB ObjectId of the collection. example: 5f8d0d55b54764421b7156c3 Name: type: string description: The human-readable name of the collection. example: Summer Festival 2026 example: Id: 5f8d0d55b54764421b7156c3 Name: Summer Festival 2026 CollectionWithItems: type: object description: A collection together with the titles it contains. required: - Id - Name properties: Id: type: string description: The internal MongoDB ObjectId of the collection. example: 5f8d0d55b54764421b7156c3 Name: type: string description: The human-readable name of the collection. example: Summer Festival 2026 Items: type: array description: The titles contained in the collection. May be empty or omitted when the collection has no titles. items: $ref: '#/components/schemas/ContentSourceResponse' example: Id: 5f8d0d55b54764421b7156c3 Name: Summer Festival 2026 Items: - Id: 6512c4a8e1d2f30099bb1077 Name: Northern Lights AddTitleToCollectionRequest: type: object description: Request body used to add an existing title to a collection. required: - EntityId properties: EntityId: type: string description: The internal MongoDB ObjectId of the title to add to the collection. example: 6512c4a8e1d2f30099bb1077 example: EntityId: 6512c4a8e1d2f30099bb1077 CreateCollectionRequest: type: object description: Request body used to create a new collection. required: - Name properties: Name: type: string description: The human-readable name for the new collection. example: Summer Festival 2026 example: Name: Summer Festival 2026 UploadStatus: type: string description: The current status of an upload. enum: - WaitingForUpload - UploadBusy - UploadPaused - UploadCanceled - UploadComplete example: UploadComplete UploadType: type: string description: The type of an upload. Dcp is a Digital Cinema Package, Vod is a video-on-demand asset, VodDRM is a DRM-protected video-on-demand asset, VodVimeo is a Vimeo video-on-demand asset, and Any allows any supported type. enum: - Dcp - Vod - VodDRM - VodVimeo - Any example: Dcp UploadConfiguration: type: object description: A reusable upload configuration that defines how an upload is received. Its id is supplied as uploaderId when creating a new upload. required: - id - name - invitationOnly properties: id: type: string description: Unique id of the upload configuration. example: 6630e5b6c7d8e9f0a1b2c3d4 name: type: string description: Human-readable name of the upload configuration. example: Feature Films - DCP invitationOnly: type: boolean description: Whether this configuration can only be used by invitation. example: false Title: type: object description: A film title as stored by Filmfetch. required: - Id - TitleOriginal - HumanId properties: Id: type: string description: The unique Filmfetch identifier of the title (24-character MongoDB ObjectId). example: 6630a1f4c2e8b9a1d4f0a201 TitleOriginal: type: string description: The original-language title of the film. example: The Last Frame TitleInternational: type: string description: The international (typically English) title of the film. May be null when not set. example: The Last Frame HumanId: type: string description: A short, human-readable reference code for the title, used in the Filmfetch UI and on delivery paperwork. example: TLF-2026-001 Note: type: string description: Free-text notes about the film. May be null. example: Delivered by the post house on 2026-05-01. Upload: type: object description: Represents a media upload and its current transfer and QC state. required: - Id - CustomerId - Type - Status properties: TitleId: type: string description: Id of the film (title) this upload is for. example: 6630a1f2c3d4e5f6a7b8c9d0 QcStatus: type: string description: Status of the Quality Control (QC) of the upload. example: Passed QcErrorMessage: type: object nullable: true description: Error message produced by QC, if the upload failed quality control. example: null ExternalId: type: object nullable: true description: Identifier of this upload in an external system, if one was supplied at creation. example: ext-2024-00123 Id: type: string description: Unique id of the upload. example: 6630b2e3d4f5a6b7c8d9e0f1 CustomerId: type: string description: Id of the customer this upload belongs to. example: 6630c3f4e5a6b7c8d9e0f1a2 CreatedAt: type: string format: date-time description: Date and time (UTC) the upload was created. example: '2024-04-30T09:15:00Z' ChangedAt: type: string format: date-time description: Date and time (UTC) the upload was last changed. example: '2024-04-30T10:42:00Z' Type: allOf: - $ref: '#/components/schemas/UploadType' description: The type of upload. example: Dcp Status: allOf: - $ref: '#/components/schemas/UploadStatus' description: The current status of the upload. example: UploadComplete Size: type: integer format: int64 description: The total size of the upload in bytes. example: 53687091200 Percentage: type: integer description: The percentage of the upload that has been received by Filmfetch. example: 100 Files: type: array description: The files contained in the upload. items: $ref: '#/components/schemas/File' Download: type: object description: A download of a media asset, either to a configured delivery point or as a one-off download. properties: Id: type: string description: Internal id of the download. example: 654b3e72111459dc1e86ece7 Files: type: array description: The files included in this download. items: $ref: '#/components/schemas/File' TitleOriginal: type: string description: The original title of the film this download is for. example: Brightbridge TitleInternational: type: string description: The international title of the film this download is for. example: Brightbridge CreatedAt: type: string format: date-time description: Date and time (UTC) the download was created. example: '2026-06-12T18:19:16Z' ChangedAt: type: string format: date-time description: Date and time (UTC) the download was last changed. example: '2026-06-12T18:45:10Z' SourceType: type: string description: The type of content being downloaded. enum: - Dcp - Vod - VodDRM - VodVimeo - Any example: Dcp Status: type: string description: The current status of the download. example: Completed Size: type: integer format: int64 description: Total size of the download in bytes. example: 268435456000 BytesDownloaded: type: integer format: int64 description: Number of bytes downloaded so far. example: 268435456000 TransferEndpoint: type: string description: Name of the transfer endpoint (delivery point) the download is sent to. Empty for a one-off download. example: Cinema City Amsterdam required: - Id - Status MediaAsset: type: object description: A delivered media package (such as a DCP or VOD asset) belonging to a title, including its files and Quality Control (QC) report. required: - Id - Name - ContainerType properties: TitleOriginal: type: string description: Original-language title of the film this media asset belongs to. example: The Silent Horizon TitleInternational: type: string description: International (English) title of the film this media asset belongs to. example: The Silent Horizon HumanId: type: string description: Human-readable reference for the media asset, used in the Filmfetch UI. example: MA-002931 FilmId: type: string description: Identifier of the film (title) this media asset belongs to. example: 507f1f77bcf86cd799439012 ContainerType: type: string description: Type of content container the media asset represents. enum: - Unknown - DCP - CPL - Any - Asset - VOD - VODAsset - VODDRM - Vimeo example: DCP Files: type: array description: The underlying storage files that make up this media asset. items: $ref: '#/components/schemas/File' QcReport: type: object description: Quality Control report for the media asset. Structure varies by container type and may include general info, image, sound, language/subtitle and quality sections. QcStatus: type: string description: Outcome of the Quality Control checks for this media asset. enum: - pending - running - passed - failed example: passed Name: type: string description: Name of the media asset, typically the DCP/package name. example: The_Silent_Horizon_FTR-1_F_EN-XX_INT_51_2K_20240115 Id: type: string description: Unique identifier of the media asset. example: 507f1f77bcf86cd799439011 Changed: type: string format: date-time description: Timestamp (UTC) of the last modification to the media asset. example: '2024-01-15T09:32:11Z' Created: type: string format: date-time description: Timestamp (UTC) at which the media asset was created. example: '2024-01-14T18:05:47Z' DeliveryPoint: type: object description: A transfer endpoint (delivery point) configured for your account, usable as the destination of a download. properties: Id: type: string description: Internal id of the delivery point. example: 654b3e72111459dc1e86ecf0 Name: type: string description: Name of the delivery point. example: Cinema City Amsterdam required: - Id - Name GeneralInfo: type: object description: General information section of a DCP Quality Control report. properties: ContentTitleText: type: string description: Full content title text as recorded in the DCP composition playlist. example: The_Silent_Horizon_FTR-1_F_EN-XX_INT_51_2K_20240115 CPL_UUID: type: string description: UUID of the Composition Playlist (CPL) of the DCP. example: urn:uuid:8c9d2f3a-1b4e-4c7d-9a6f-2e5b8d1c4a7f DCP_Size: type: string description: Total size of the DCP as a human-readable string. example: 24.6 GB DCP_Standard: type: string description: DCP standard the package conforms to. enum: - SMPTE - Interop example: SMPTE PackageType: type: string description: Type of DCP package. enum: - OV - VF example: OV Duration: type: string description: Playback duration of the content (HH:MM:SS). example: 01:54:23 Frame_rate: type: integer description: Frame rate of the content in frames per second. example: 24 Creator: type: string description: Tool or organization that created the DCP. example: easyDCP Creator ContentKind: type: string description: Kind of content in the DCP. enum: - feature - trailer - advertisement - short - test - teaser - psa example: feature Encrypted: type: string description: Whether the DCP is encrypted. enum: - 'Yes' - 'No' example: 'No' PlayableOnDoremi: type: string description: Whether the DCP is playable on Doremi servers. enum: - 'Yes' - 'No' example: 'Yes' Quality: type: object description: Quality summary section of a DCP Quality Control report. properties: PlayableOnDoremi: type: string description: Whether the DCP is playable on Doremi servers. enum: - 'Yes' - 'No' example: 'Yes' ErrorCount: type: integer description: Number of errors found during Quality Control. example: 0 WarningCount: type: integer description: Number of warnings found during Quality Control. example: 2 File: type: object description: A single file that is part of an upload or download. required: - Id - Name - Status properties: Id: type: string description: Unique id of the file. example: 6630d4a5b6c7d8e9f0a1b2c3 Status: type: string description: The current status of the file transfer. example: UploadComplete CreatedAt: type: string format: date-time description: Date and time (UTC) the file record was created. example: '2024-04-30T09:15:00Z' ChangedAt: type: string format: date-time description: Date and time (UTC) the file record was last changed. example: '2024-04-30T10:42:00Z' Name: type: string description: The file name. example: FEATURE_F_EN-XX_51_2K_20240430.mxf NameAndPath: type: string description: The file name including its relative path within the upload. example: DCP/FEATURE_F_EN-XX_51_2K_20240430.mxf Size: type: integer format: int64 description: The total size of the file in bytes. example: 53687091200 Uploaded: type: integer format: int64 description: The number of bytes received by Filmfetch so far. example: 53687091200 PercentageUploaded: type: integer description: The percentage of the file that has been uploaded. example: 100 CreateUploadRequest: type: object description: > Request payload for creating a new upload. Every upload must belong to a title, so provide exactly one of titleId or film. Use titleId to attach the upload to a title that already exists (this is how you add more uploads to an existing title). Use film to create a new title together with this upload, which saves a separate call when creating the first upload for a title. required: - uploaderId properties: uploaderId: type: string description: Id of the upload configuration that this upload must be linked to. example: 6630e5b6c7d8e9f0a1b2c3d4 titleId: type: string description: > Id of an existing title to attach this upload to. Mutually exclusive with film. The title must belong to your account. Use this to add additional uploads to a title that already exists. example: 6630a1f2c3d4e5f6a7b8c9d0 film: allOf: - $ref: '#/components/schemas/CreateTitleInline' description: > A new title to create together with this upload. Mutually exclusive with titleId. externalId: type: string description: Your own reference for this upload in an external system. example: ext-2024-00123 CreateTitleInline: type: object description: > Inline title to create together with the upload. Mutually exclusive with titleId. If a title with the same externalId already exists for your account, that existing title is reused instead of creating a duplicate. required: - titleOriginal properties: titleOriginal: type: string description: The original-language title. example: La Haine titleInternational: type: string description: The international (e.g. English) title. example: Hate externalId: type: string description: Your own reference for this title in an external system. Used to de-duplicate titles. example: film-2024-00045 CreateDownloadRequest: type: object description: Body for creating a download. Maps to the public create-download request, where deliverypointId selects the delivery point (EndPointId internally). properties: deliverypointId: type: string description: Id of the delivery point to send the download to. When omitted, the download is created as a one-off download. example: 654b3e72111459dc1e86ecf0 example: deliverypointId: 654b3e72111459dc1e86ecf0 GetUploadsResponse: type: object description: A paginated list of uploads. required: - count - items properties: count: type: integer description: Total number of uploads matching the query across all pages. example: 1 items: type: array description: The uploads on the current page. items: $ref: '#/components/schemas/Upload' GetTitlesResponse: type: object description: A paginated set of title search results. required: - total - items properties: total: type: integer format: int64 description: The total number of titles matching the search criteria across all pages. example: 42 items: type: array description: The titles on the current page. items: $ref: '#/components/schemas/ContentSourceSearchResponse' example: total: 42 items: - Id: 6630a1f4c2e8b9a1d4f0a201 Created: '2026-05-01T09:12:33Z' Changed: '2026-05-12T14:08:51Z' TitleOriginal: The Last Frame TitleInternational: The Last Frame Tags: - feature - drama HumanId: TLF-2026-001 Collections: - Id: 6630a1f4c2e8b9a1d4f0a300 Name: Summer Releases 2026 CreateTitleRequest: type: object description: Payload for creating a new title. required: - TitleOriginal properties: TitleOriginal: type: string description: The original-language title of the film. example: The Last Frame TitleInternational: type: string description: The international (typically English) title of the film. example: The Last Frame Tags: type: array description: A list of free-text tags used to categorize the title. items: type: string example: - feature - drama ExternalId: type: string description: The identifier of this title in the caller's external system, used to cross-reference Filmfetch and the caller's own records. example: EXT-99001 AddToCollectionId: type: string description: Optional id of an existing collection the new title should be added to immediately after creation (24-character MongoDB ObjectId). example: 6630a1f4c2e8b9a1d4f0a300 ContentSourceResponse: type: object description: The full representation of a title, including its content containers. required: - Id - CreatedAt - ChangedAt - TitleOriginal - Tags - HumanId - ContentContainers properties: Id: type: string description: The unique Filmfetch identifier of the title (24-character MongoDB ObjectId). example: 6630a1f4c2e8b9a1d4f0a201 CreatedAt: type: string format: date-time description: The UTC timestamp at which the title was created. example: '2026-05-01T09:12:33Z' ChangedAt: type: string format: date-time description: The UTC timestamp at which the title was last modified. example: '2026-05-12T14:08:51Z' TitleOriginal: type: string description: The original-language title of the film. example: The Last Frame TitleInternational: type: string description: The international (typically English) title of the film. May be null when not set. example: The Last Frame Tags: type: array description: The free-text tags assigned to the title. items: type: string example: - feature - drama ExternalId: type: string description: The identifier of this title in the caller's external system. example: EXT-99001 HumanId: type: string description: A short, human-readable reference code for the title. example: TLF-2026-001 Note: type: string description: Free-text notes about the title. May be null. example: Delivered by the post house on 2026-05-01. CollectionIds: type: array description: The ids of the collections this title belongs to (each a 24-character MongoDB ObjectId). items: type: string description: A collection id (24-character MongoDB ObjectId). example: 6630a1f4c2e8b9a1d4f0a300 example: - 6630a1f4c2e8b9a1d4f0a300 ContentContainers: description: The content containers (deliverable media packages such as CPL or VOD) associated with this title. oneOf: - $ref: '#/components/schemas/CplContentContainerResponse' - $ref: '#/components/schemas/VodContentContainerResponse' - $ref: '#/components/schemas/AnyContentContainerResponse' ContentSourceSearchResponse: type: object description: A lightweight title representation returned by the title search endpoint. required: - Id - Created - Changed - TitleOriginal - Tags - HumanId - Collections properties: Id: type: string description: The unique Filmfetch identifier of the title (24-character MongoDB ObjectId). example: 6630a1f4c2e8b9a1d4f0a201 Created: type: string format: date-time description: The UTC timestamp at which the title was created. example: '2026-05-01T09:12:33Z' Changed: type: string format: date-time description: The UTC timestamp at which the title was last modified. example: '2026-05-12T14:08:51Z' TitleOriginal: type: string description: The original-language title of the film. example: The Last Frame TitleInternational: type: string description: The international (typically English) title of the film. May be null when not set. example: The Last Frame Tags: type: array description: The free-text tags assigned to the title. items: type: string example: - feature - drama Collections: type: array description: The collections this title belongs to. items: type: object required: - Id - Name properties: Id: type: string description: The collection id (24-character MongoDB ObjectId). example: 6630a1f4c2e8b9a1d4f0a300 Name: type: string description: The display name of the collection. example: Summer Releases 2026 HumanId: type: string description: A short, human-readable reference code for the title. example: TLF-2026-001 CplContentContainerResponse: type: object description: A CPL (Composition Playlist) content container of a DCP, including its Quality Control report and the CPL file identifier used to fetch the CPL XML. required: - Id - ContainerType properties: Id: type: string description: Unique identifier of the content container. example: 507f1f77bcf86cd799439021 CreatedAt: type: string format: date-time description: Timestamp (UTC) at which the content container was created. example: '2024-01-14T18:05:47Z' ChangedAt: type: string format: date-time description: Timestamp (UTC) of the last modification to the content container. example: '2024-01-15T09:32:11Z' ContainerType: type: string description: Type of content container; always CPL for this response. enum: - CPL example: CPL QcReport: type: object description: Quality Control report for the CPL container. Name: type: string description: Name of the CPL content container. example: The_Silent_Horizon_FTR-1_F_EN-XX_INT_51_2K_20240115 TotalSize: type: string description: Total size of the CPL container as a human-readable string. example: 24.6 GB QcStatus: type: string description: Outcome of the Quality Control checks for this container. enum: - pending - running - passed - failed example: passed CplFileId: type: string description: Identifier of the CPL file, used with GET /v2/media-assets/cpl/{cplFileId} to fetch the CPL XML. example: 507f1f77bcf86cd799439033 VodContentContainerResponse: type: object description: A VOD (Video On Demand) content container with its Quality Control report. required: - Id - ContainerType properties: Id: type: string description: Unique identifier of the content container. example: 507f1f77bcf86cd799439022 CreatedAt: type: string format: date-time description: Timestamp (UTC) at which the content container was created. example: '2024-01-14T18:05:47Z' ChangedAt: type: string format: date-time description: Timestamp (UTC) of the last modification to the content container. example: '2024-01-15T09:32:11Z' ContainerType: type: string description: Type of content container; always VOD for this response. enum: - VOD example: VOD QcReport: type: object description: Quality Control report for the VOD container. Name: type: string description: Name of the VOD content container. example: The_Silent_Horizon_VOD_EN_HD TotalSize: type: integer format: int64 description: Total size of the VOD container in bytes. example: 8589934592 QcStatus: type: string description: Outcome of the Quality Control checks for this container. enum: - pending - running - passed - failed example: passed AnyContentContainerResponse: type: object description: A generic (ANY) content container with its Quality Control report. required: - Id - ContainerType properties: Id: type: string description: Unique identifier of the content container. example: 507f1f77bcf86cd799439023 CreatedAt: type: string format: date-time description: Timestamp (UTC) at which the content container was created. example: '2024-01-14T18:05:47Z' ChangedAt: type: string format: date-time description: Timestamp (UTC) of the last modification to the content container. example: '2024-01-15T09:32:11Z' ContainerType: type: string description: Type of content container; Any for a generic container. enum: - Any example: Any QcReport: type: object description: Quality Control report for the container. Name: type: string description: Name of the content container. example: The_Silent_Horizon_Assets TotalSize: type: integer format: int64 description: Total size of the container in bytes. example: 1073741824 GetMediaAssetsResponse: type: object description: Paginated list of media assets. required: - total - items properties: total: type: integer format: int64 description: Total number of media assets matching the query across all pages. example: 42 items: type: array description: The media assets on the current page. items: $ref: '#/components/schemas/MediaAsset' GetDeliveryPointsResponse: type: array description: List of the delivery points configured for your account. items: $ref: '#/components/schemas/DeliveryPoint' example: - Id: 654b3e72111459dc1e86ecf0 Name: Cinema City Amsterdam - Id: 654b3e72111459dc1e86ecf1 Name: Pathe Rotterdam GetDownloadsResponse: type: object description: Paginated list of downloads. properties: Count: type: integer description: Total number of downloads matching the query, across all pages. example: 1 Items: type: array description: The downloads on the current page. items: $ref: '#/components/schemas/DownloadRequestResponse' required: - Count - Items example: Count: 1 Items: - Id: 654b3e72111459dc1e86ece7 TitleOriginal: Brightbridge TitleInternational: Brightbridge CreatedAt: '2026-06-12T18:19:16Z' ChangedAt: '2026-06-12T18:45:10Z' SourceType: Dcp Status: Completed Size: 268435456000 BytesDownloaded: 268435456000 TransferEndpoint: Cinema City Amsterdam IsOneOff: false Percentage: 100 DownloadRequestResponse: type: object description: A download as returned in the paginated downloads list, with progress and related media-asset details. properties: Id: type: string description: Internal id of the download. example: 654b3e72111459dc1e86ece7 Files: description: The file location details for this download. $ref: '#/components/schemas/DownloadRequestFileResponse' TitleOriginal: type: string description: The original title of the film this download is for. example: Brightbridge TitleInternational: type: string description: The international title of the film this download is for. example: Brightbridge CreatedAt: type: string format: date-time description: Date and time (UTC) the download was created. example: '2026-06-12T18:19:16Z' ChangedAt: type: string format: date-time description: Date and time (UTC) the download was last changed. example: '2026-06-12T18:45:10Z' SourceType: type: string description: The type of content being downloaded. enum: - Dcp - Vod - VodDRM - VodVimeo - Any example: Dcp Status: type: string description: The current status of the download. example: Completed Size: type: integer format: int64 description: Total size of the download in bytes. example: 268435456000 BytesDownloaded: type: integer format: int64 description: Number of bytes downloaded so far. example: 268435456000 TransferEndpoint: type: string description: Name of the transfer endpoint (delivery point) the download is sent to. Empty for a one-off download. example: Cinema City Amsterdam IsOneOff: type: boolean description: Read-only. True when the download has no delivery point (TransferEndpoint is null, empty, or an empty ObjectId). example: false Score: type: number description: Relevance score of this download when returned from a search. example: 1 HumanId: type: string description: Human-readable identifier of the film. example: BRB-0001 FilmId: type: string description: Internal id of the film this download is for. example: 6a2c4da45f00109e85f1b15e SpeedBytesPerSecond: type: integer format: int64 description: Current transfer speed in bytes per second. example: 125000000 Tags: type: array description: Tags associated with the download. items: type: string example: - feature DestinationId: type: string nullable: true description: Internal id of the download destination, when applicable. example: 654b3e72111459dc1e86ecf0 SizeString: type: string description: Human-readable formatted total size. example: 250 GB Percentage: type: integer description: Percentage of the download that has completed (0-100). example: 100 MediaAsset: description: Summary of the media asset this download was created from. $ref: '#/components/schemas/MediaAssetShortResponse' Collections: type: array description: Collections the underlying title belongs to. items: type: object example: [] TransferEndpointNameLower: type: string description: Lower-cased transfer endpoint name, used for sorting and matching. example: cinema city amsterdam required: - Id - Status DownloadRequestFileResponse: type: object description: Location details of a download file in object storage. properties: Region: type: string description: AWS region the file is stored in. example: eu-west-1 S3Bucket: type: string description: Name of the S3 bucket holding the file. example: filmfetch-deliveries S3Key: type: string description: S3 object key of the file within the bucket. example: deliveries/654b3e72111459dc1e86ece7/feature.mxf Size: type: integer format: int64 description: Size of the file in bytes. example: 268435456000 Root: type: string description: Root path of the file within the delivery package. example: /DCP/BRIGHTBRIDGE_FTR MediaAssetShortResponse: type: object description: Lightweight representation of a media asset, embedded in download requests. required: - Id - Name properties: Id: type: string description: Unique identifier of the media asset. example: 507f1f77bcf86cd799439011 Name: type: string description: Name of the media asset, typically the DCP/package name. example: The_Silent_Horizon_FTR-1_F_EN-XX_INT_51_2K_20240115 QcReport: type: object nullable: true description: Quality Control report for the media asset, or null when no QC report is available. ContainerType: type: string description: Type of content container of a media asset. enum: - Unknown - DCP - CPL - Any - Asset - VOD - VODAsset - VODDRM - Vimeo example: DCP requestBodies: CreateUploadRequest: content: application/json: schema: $ref: '#/components/schemas/CreateUploadRequest' CreateTitleRequest: content: application/json: schema: $ref: '#/components/schemas/CreateTitleRequest' CreateDownloadRequest: content: application/json: schema: $ref: '#/components/schemas/CreateDownloadRequest' security: - ApiKeyAuth: [] paths: /v2/collection: get: tags: - collections summary: List collections description: Returns all collections available to the authenticated account. Each entry contains only the collection id and name; use the get-by-id operation to retrieve its titles. operationId: getCollections responses: '200': description: A list of collections. content: application/json: schema: type: array items: $ref: '#/components/schemas/CollectionBasic' example: - Id: 5f8d0d55b54764421b7156c3 Name: Summer Festival 2026 - Id: 6620a1f2c9e77b0012ab34cd Name: Arthouse Premieres '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' post: tags: - collections summary: Create a new collection description: Creates a new, empty collection for the authenticated account and returns its basic representation, including the generated id. operationId: createCollection requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCollectionRequest' example: Name: Summer Festival 2026 responses: '201': description: The collection was created. content: application/json: schema: $ref: '#/components/schemas/CollectionBasic' example: Id: 5f8d0d55b54764421b7156c3 Name: Summer Festival 2026 '400': description: The request body is invalid (for example, a missing or empty name). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/collection/{collectionId}: get: tags: - collections summary: Get a collection by id description: Returns a single collection together with the titles it contains. operationId: getCollectionById parameters: - name: collectionId in: path required: true description: The internal id of the collection to retrieve. schema: type: string example: 5f8d0d55b54764421b7156c3 responses: '200': description: The requested collection, including its titles. content: application/json: schema: $ref: '#/components/schemas/CollectionWithItems' example: Id: 5f8d0d55b54764421b7156c3 Name: Summer Festival 2026 Items: - Id: 6512c4a8e1d2f30099bb1077 Name: Northern Lights '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No collection exists with the given id. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/collection/{collectionId}/title: post: tags: - collections summary: Add a title to a collection description: Associates an existing title with the given collection and returns the updated collection, including its titles. operationId: addTitleToCollection requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddTitleToCollectionRequest' example: EntityId: 6512c4a8e1d2f30099bb1077 parameters: - name: collectionId in: path required: true description: The internal id of the collection to add the title to. schema: type: string example: 5f8d0d55b54764421b7156c3 responses: '200': description: The updated collection, including the newly added title. content: application/json: schema: $ref: '#/components/schemas/CollectionWithItems' example: Id: 5f8d0d55b54764421b7156c3 Name: Summer Festival 2026 Items: - Id: 6512c4a8e1d2f30099bb1077 Name: Northern Lights '400': description: The request body is invalid (for example, a missing title id). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No collection exists with the given id, or the referenced title was not found. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/collection/{collectionId}/title/{titleId}: delete: tags: - collections summary: Remove a title from a collection description: Disassociates a title from the given collection and returns the updated collection. The title itself is not deleted. operationId: removeTitleFromCollection parameters: - name: collectionId in: path required: true description: The internal id of the collection to remove the title from. schema: type: string example: 5f8d0d55b54764421b7156c3 - name: titleId in: path required: true description: The internal id of the title to remove from the collection. schema: type: string example: 6512c4a8e1d2f30099bb1077 responses: '200': description: The updated collection, with the title removed. content: application/json: schema: $ref: '#/components/schemas/CollectionWithItems' example: Id: 5f8d0d55b54764421b7156c3 Name: Summer Festival 2026 Items: [] '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No collection exists with the given id, or the title is not part of the collection. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/upload/{uploadId}: get: tags: - uploads summary: Get an upload by id description: Returns a single upload by its identifier, including its files and current upload status. Set isExternalId to true to look the upload up by its external id instead of its Filmfetch id. operationId: getUpload parameters: - name: uploadId in: path required: true description: Identifier of the upload. By default this is the Filmfetch upload id; if isExternalId is true it is the external id assigned at creation time. schema: type: string example: 6630b2e3d4f5a6b7c8d9e0f1 - name: isExternalId in: query required: false description: When true, uploadId is treated as the external id rather than the Filmfetch upload id. schema: type: boolean example: false responses: '200': description: The requested upload. content: application/json: schema: $ref: '#/components/schemas/Upload' example: TitleId: 6630a1f2c3d4e5f6a7b8c9d0 QcStatus: Passed QcErrorMessage: null ExternalId: ext-2024-00123 Id: 6630b2e3d4f5a6b7c8d9e0f1 CustomerId: 6630c3f4e5a6b7c8d9e0f1a2 CreatedAt: '2024-04-30T09:15:00Z' ChangedAt: '2024-04-30T10:42:00Z' Type: Dcp Status: UploadComplete Size: 53687091200 Percentage: 100 Files: - Id: 6630d4a5b6c7d8e9f0a1b2c3 Status: UploadComplete CreatedAt: '2024-04-30T09:15:00Z' ChangedAt: '2024-04-30T10:42:00Z' Name: FEATURE_F_EN-XX_51_2K_20240430.mxf NameAndPath: DCP/FEATURE_F_EN-XX_51_2K_20240430.mxf Size: 53687091200 Uploaded: 53687091200 PercentageUploaded: 100 '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The API key is not allowed to access this upload. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No upload exists with the given identifier. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/upload: get: tags: - uploads summary: List uploads description: Returns a paginated list of uploads belonging to the authenticated customer, most recently created first. operationId: getUploads parameters: - name: page in: query required: false description: One-based page number of the result set to return. schema: type: number example: 1 - name: pageSize in: query required: false description: Maximum number of uploads to return per page. schema: type: number example: 10 responses: '200': description: A paginated list of uploads. content: application/json: schema: $ref: '#/components/schemas/GetUploadsResponse' example: count: 1 items: - TitleId: 6630a1f2c3d4e5f6a7b8c9d0 QcStatus: Passed QcErrorMessage: null ExternalId: ext-2024-00123 Id: 6630b2e3d4f5a6b7c8d9e0f1 CustomerId: 6630c3f4e5a6b7c8d9e0f1a2 CreatedAt: '2024-04-30T09:15:00Z' ChangedAt: '2024-04-30T10:42:00Z' Type: Dcp Status: UploadComplete Size: 53687091200 Percentage: 100 Files: - Id: 6630d4a5b6c7d8e9f0a1b2c3 Status: UploadComplete CreatedAt: '2024-04-30T09:15:00Z' ChangedAt: '2024-04-30T10:42:00Z' Name: FEATURE_F_EN-XX_51_2K_20240430.mxf NameAndPath: DCP/FEATURE_F_EN-XX_51_2K_20240430.mxf Size: 53687091200 Uploaded: 53687091200 PercentageUploaded: 100 '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' post: tags: - uploads summary: Create a new upload description: Creates a new upload against an upload configuration and returns the created upload. The returned upload starts in the WaitingForUpload status. operationId: createUpload requestBody: $ref: '#/components/requestBodies/CreateUploadRequest' responses: '200': description: The upload was created successfully. content: application/json: schema: $ref: '#/components/schemas/Upload' example: TitleId: 6630a1f2c3d4e5f6a7b8c9d0 QcStatus: Pending QcErrorMessage: null ExternalId: ext-2024-00123 Id: 6630b2e3d4f5a6b7c8d9e0f1 CustomerId: 6630c3f4e5a6b7c8d9e0f1a2 CreatedAt: '2024-04-30T09:15:00Z' ChangedAt: '2024-04-30T09:15:00Z' Type: Dcp Status: WaitingForUpload Size: 0 Percentage: 0 Files: [] '400': description: The request body is invalid or required fields are missing. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/uploader-configurations: get: tags: - uploads summary: Get upload configurations description: Returns the upload configurations available to the authenticated customer. An upload configuration is referenced by its id when creating a new upload. operationId: getUploadConfigurations responses: '200': description: The list of available upload configurations. content: application/json: schema: type: array items: $ref: '#/components/schemas/UploadConfiguration' example: - id: 6630e5b6c7d8e9f0a1b2c3d4 name: Feature Films - DCP invitationOnly: false - id: 6630f6c7d8e9f0a1b2c3d4e5 name: Festival Submissions invitationOnly: true '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: An unexpected error occurred while retrieving the configurations. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/download: get: tags: - downloads summary: List downloads description: 'Returns a paginated list of the downloads on your account. Use the page and pageSize query parameters to page through the results. ' operationId: getDownloads parameters: - name: page in: query required: false description: The page number to retrieve, in combination with pageSize. For example page 3 with pageSize 10 returns downloads 21 - 30. schema: type: number example: 1 - name: pageSize in: query required: false description: The number of downloads to return per page, in combination with page. schema: type: number example: 10 responses: '200': description: A paginated list of downloads. content: application/json: schema: $ref: '#/components/schemas/GetDownloadsResponse' example: Count: 1 Items: - Id: 654b3e72111459dc1e86ece7 Files: Region: eu-west-1 S3Bucket: filmfetch-deliveries S3Key: deliveries/654b3e72111459dc1e86ece7/feature.mxf Size: 268435456000 Root: /DCP/BRIGHTBRIDGE_FTR TitleOriginal: Brightbridge TitleInternational: Brightbridge CreatedAt: '2026-06-12T18:19:16Z' ChangedAt: '2026-06-12T18:45:10Z' SourceType: Dcp Status: Completed Size: 268435456000 BytesDownloaded: 268435456000 TransferEndpoint: Cinema City Amsterdam IsOneOff: false Score: 1 HumanId: BRB-0001 FilmId: 6a2c4da45f00109e85f1b15e SpeedBytesPerSecond: 125000000 Tags: - feature DestinationId: 654b3e72111459dc1e86ecf0 SizeString: 250 GB Percentage: 100 MediaAsset: Id: 654b3e72111459dc1e86ece9 Name: BRIGHTBRIDGE_FTR-1_F_EN-XX_INT_51_2K_20260601 QcReport: null Collections: [] TransferEndpointNameLower: cinema city amsterdam '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/download/media-asset/{mediaAssetId}: post: tags: - downloads summary: Create a download for a media asset description: 'Creates a download for the given media asset and returns it. Provide a deliverypointId in the body to send the download to a configured delivery point, or omit it to create a one-off download. ' operationId: postDownload parameters: - name: mediaAssetId in: path required: true description: Internal id of the media asset to create the download for. schema: type: string example: 654b3e72111459dc1e86ece7 requestBody: $ref: '#/components/requestBodies/CreateDownloadRequest' responses: '201': description: The created download. content: application/json: schema: $ref: '#/components/schemas/Download' example: Id: 654b3e72111459dc1e86ece7 Files: - Region: eu-west-1 S3Bucket: filmfetch-deliveries S3Key: deliveries/654b3e72111459dc1e86ece7/feature.mxf Size: 268435456000 Root: /DCP/BRIGHTBRIDGE_FTR TitleOriginal: Brightbridge TitleInternational: Brightbridge CreatedAt: '2026-06-12T18:19:16Z' ChangedAt: '2026-06-12T18:19:16Z' SourceType: Dcp Status: WaitingForDownload Size: 268435456000 BytesDownloaded: 0 TransferEndpoint: Cinema City Amsterdam '400': description: Invalid request, for example an unknown delivery point id. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No media asset exists with the given id. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Server error. /v2/title: get: tags: - titles summary: Search titles description: 'Returns a paginated list of titles. Supports keyword search and pagination through the `query`, `page` and `pageSize` parameters. This operation is rate limited. ' operationId: getTitles parameters: - name: page in: query required: false schema: type: number default: 1 description: The page number to retrieve. Combined with `pageSize` it determines which slice of results is returned. For example, page 3 with pageSize 10 returns titles 31 - 40. example: 1 - name: pageSize in: query required: false schema: type: number default: 10 description: The number of titles to return per page. Combined with `page` it determines which slice of results is returned. For example, page 3 with pageSize 10 returns titles 31 - 40. example: 10 - name: query in: query required: false schema: type: string description: Optional free-text search term used to filter titles by their original or international title. example: The Last Frame responses: '200': description: A paginated list of titles matching the search criteria. content: application/json: schema: $ref: '#/components/schemas/GetTitlesResponse' example: total: 42 items: - Id: 6630a1f4c2e8b9a1d4f0a201 Created: '2026-05-01T09:12:33Z' Changed: '2026-05-12T14:08:51Z' TitleOriginal: The Last Frame TitleInternational: The Last Frame Tags: - feature - drama HumanId: TLF-2026-001 Collections: - Id: 6630a1f4c2e8b9a1d4f0a300 Name: Summer Releases 2026 '400': description: The supplied query parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Too many requests. The title search rate limit has been exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' post: tags: - titles summary: Create a new title description: Creates a new title and returns the full created title resource. operationId: createTitle requestBody: $ref: '#/components/requestBodies/CreateTitleRequest' responses: '200': description: The title was created successfully. content: application/json: schema: $ref: '#/components/schemas/ContentSourceResponse' example: Id: 6630a1f4c2e8b9a1d4f0a201 CreatedAt: '2026-05-01T09:12:33Z' ChangedAt: '2026-05-01T09:12:33Z' TitleOriginal: The Last Frame TitleInternational: The Last Frame Tags: - feature - drama ExternalId: EXT-99001 HumanId: TLF-2026-001 Note: Delivered by the post house on 2026-05-01. CollectionIds: - 6630a1f4c2e8b9a1d4f0a300 ContentContainers: [] '400': description: The request body is invalid or required fields are missing. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/title/{titleId}: get: tags: - titles summary: Get a title by id description: 'Returns a single title by its identifier, including its content containers. By default the `titleId` is treated as the Filmfetch id; set `isExternalId` to true to look the title up by its external system id instead. This operation is rate limited. ' operationId: getTitle parameters: - name: titleId in: path required: true schema: type: string description: The identifier of the title to retrieve. By default this is the Filmfetch title id (a 24-character MongoDB ObjectId). When `isExternalId` is true, this is the external system id instead. example: 6630a1f4c2e8b9a1d4f0a201 - name: isExternalId in: query required: false schema: type: boolean default: false description: When true, `titleId` is interpreted as the external system id rather than the Filmfetch title id. example: false responses: '200': description: The requested title. content: application/json: schema: $ref: '#/components/schemas/ContentSourceResponse' example: Id: 6630a1f4c2e8b9a1d4f0a201 CreatedAt: '2026-05-01T09:12:33Z' ChangedAt: '2026-05-12T14:08:51Z' TitleOriginal: The Last Frame TitleInternational: The Last Frame Tags: - feature - drama ExternalId: EXT-99001 HumanId: TLF-2026-001 Note: Delivered by the post house on 2026-05-01. CollectionIds: - 6630a1f4c2e8b9a1d4f0a300 ContentContainers: [] '401': description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The API key is not allowed to access this title. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No title was found for the supplied identifier. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/media-asset: get: tags: - media assets summary: List media assets description: Returns a paginated list of media assets across your account. Each media asset represents a delivered package (DCP, VOD, etc.) belonging to a title, together with its files and Quality Control report. operationId: getMediaAssets parameters: - name: page in: query required: false description: One-based page number of the result set to return. Defaults to the first page when omitted. schema: type: number example: 1 - name: pageSize in: query required: false description: Maximum number of media assets to return per page. schema: type: number example: 10 responses: '200': description: A paginated list of media assets. content: application/json: schema: $ref: '#/components/schemas/GetMediaAssetsResponse' example: total: 42 items: - Id: 507f1f77bcf86cd799439011 TitleOriginal: The Silent Horizon TitleInternational: The Silent Horizon HumanId: MA-002931 FilmId: 507f1f77bcf86cd799439012 ContainerType: DCP Name: The_Silent_Horizon_FTR-1_F_EN-XX_INT_51_2K_20240115 QcStatus: passed Files: - Region: eu-west-2 S3Bucket: filmfetch-assets-prod S3Key: 507f1f77bcf86cd799439011/cpl.xml Size: 24576 Root: dcp/ QcReport: {} Changed: '2024-01-15T09:32:11Z' Created: '2024-01-14T18:05:47Z' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/media-assets/cpl/{cplFileId}: get: tags: - media assets summary: Get the CPL of a DCP description: Returns the Composition Playlist (CPL) of a DCP as XML. The cplFileId is exposed on the media asset's CPL content container. operationId: getCpl parameters: - name: cplFileId in: path required: true description: Identifier of the CPL file, taken from the CplFileId field of a media asset's CPL content container. schema: type: string example: 507f1f77bcf86cd799439033 responses: '200': description: The CPL as XML. content: application/xml: example: "\n\n ...\n\n" '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No CPL was found for the given cplFileId. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/media-asset/{titleId}/{mediaAssetId}: delete: tags: - media assets summary: Delete media asset description: Deletes a media asset from a title and returns the updated content source for that title. operationId: deleteMediaAsset parameters: - name: titleId in: path required: true description: Identifier of the title the media asset belongs to. schema: type: string example: 507f1f77bcf86cd799439012 - name: mediaAssetId in: path required: true description: Identifier of the media asset to delete. schema: type: string example: 507f1f77bcf86cd799439011 responses: '200': description: The media asset was deleted; the updated content source for the title is returned. content: application/json: schema: $ref: '#/components/schemas/ContentSourceResponse' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: The title or media asset could not be found. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/delivery-point: get: tags: - delivery points summary: List delivery points description: 'Returns the transfer endpoints (delivery points) configured for your account. Use a delivery point id as the deliverypointId when creating a download. ' operationId: getDeliveryPoints responses: '200': description: The delivery points configured for your account. content: application/json: schema: $ref: '#/components/schemas/GetDeliveryPointsResponse' example: - Id: 654b3e72111459dc1e86ecf0 Name: Cinema City Amsterdam - Id: 654b3e72111459dc1e86ecf1 Name: Pathe Rotterdam '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' /v2/webhooks: get: tags: - webhooks summary: List webhook subscriptions description: Returns the active webhook subscriptions registered for your account. The signing secret is never included here; it is only returned once when the subscription is created. operationId: listWebhooks responses: '200': description: The list of webhook subscriptions for your account. content: application/json: schema: type: array items: $ref: '#/components/schemas/WebhookSubscription' example: - id: 6630a1e2f4b1c9a0d3e4f5a6 url: https://your-app.example.com/filmfetch-hook eventTypes: - upload.created - upload.updated description: Production webhook isActive: true created: '2026-06-12T18:19:16Z' lastDeliveryAt: '2026-06-12T18:40:02Z' lastDeliveryStatus: success secret: null '401': description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: Missing or invalid API key. post: tags: - webhooks summary: Create a webhook subscription description: Registers a public https endpoint to receive signed event deliveries. The HMAC signing secret is returned only in this response, so store it immediately, you cannot retrieve it again later. operationId: createWebhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptionInput' example: url: https://your-app.example.com/filmfetch-hook eventTypes: - upload.created - upload.updated description: Production webhook responses: '200': description: The created webhook subscription, including the one-time signing secret. content: application/json: schema: $ref: '#/components/schemas/WebhookSubscription' example: id: 6630a1e2f4b1c9a0d3e4f5a6 url: https://your-app.example.com/filmfetch-hook eventTypes: - upload.created - upload.updated description: Production webhook isActive: true created: '2026-06-12T18:19:16Z' lastDeliveryAt: null lastDeliveryStatus: null secret: whsec_3f8a1c2d9b4e6f70a1b2c3d4e5f60718 '400': description: The url is not a valid public https endpoint or an unknown event type was supplied. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_url message: Url must use https. '401': description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: Missing or invalid API key. /v2/webhooks/{id}: get: tags: - webhooks summary: Get a webhook subscription description: Returns a single webhook subscription by its id. The signing secret is not included. operationId: getWebhook parameters: - name: id in: path required: true description: The id of the webhook subscription to retrieve. schema: type: string example: 6630a1e2f4b1c9a0d3e4f5a6 responses: '200': description: The requested webhook subscription. content: application/json: schema: $ref: '#/components/schemas/WebhookSubscription' example: id: 6630a1e2f4b1c9a0d3e4f5a6 url: https://your-app.example.com/filmfetch-hook eventTypes: - upload.created - upload.updated description: Production webhook isActive: true created: '2026-06-12T18:19:16Z' lastDeliveryAt: '2026-06-12T18:40:02Z' lastDeliveryStatus: success secret: null '401': description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: Missing or invalid API key. '404': description: No webhook subscription exists with the given id for your account. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: not_found message: Webhook subscription not found. delete: tags: - webhooks summary: Delete a webhook subscription description: Permanently removes a webhook subscription. After deletion no further events are delivered to its endpoint. operationId: deleteWebhook parameters: - name: id in: path required: true description: The id of the webhook subscription to delete. schema: type: string example: 6630a1e2f4b1c9a0d3e4f5a6 responses: '204': description: The webhook subscription was deleted. No content is returned. '401': description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: Missing or invalid API key. '404': description: No webhook subscription exists with the given id for your account. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: not_found message: Webhook subscription not found. webhooks: upload.created: post: tags: - webhooks summary: upload.created description: Sent when a new upload is created on your account. The data block carries the initial upload and QC status. operationId: webhookUploadCreated parameters: - $ref: '#/components/parameters/WebhookEventHeader' - $ref: '#/components/parameters/WebhookDeliveryHeader' - $ref: '#/components/parameters/WebhookSignatureHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEvent' example: id: 6630a1e2f4b1c9a0d3e4f5a6 event: upload.created createdAt: '2026-06-12T18:19:16Z' resource: type: upload id: 6a2c4da45f00109e85f1b15e customerId: 6a2bd5b71b1e7e575738920c data: uploadStatus: WaitingForUpload qcStatus: None responses: '200': description: Acknowledge receipt with any 2xx status. upload.updated: post: tags: - webhooks summary: upload.updated description: Sent when an upload changes, for example when its status or QC result changes. Progress-only ticks are not sent. operationId: webhookUploadUpdated parameters: - $ref: '#/components/parameters/WebhookEventHeader' - $ref: '#/components/parameters/WebhookDeliveryHeader' - $ref: '#/components/parameters/WebhookSignatureHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEvent' example: id: 6630a1e2f4b1c9a0d3e4f5a7 event: upload.updated createdAt: '2026-06-12T18:40:02Z' resource: type: upload id: 6a2c4da45f00109e85f1b15e customerId: 6a2bd5b71b1e7e575738920c data: uploadStatus: UploadComplete qcStatus: Passed responses: '200': description: Acknowledge receipt with any 2xx status. upload.deleted: post: tags: - webhooks summary: upload.deleted description: Sent when an upload is deleted. operationId: webhookUploadDeleted parameters: - $ref: '#/components/parameters/WebhookEventHeader' - $ref: '#/components/parameters/WebhookDeliveryHeader' - $ref: '#/components/parameters/WebhookSignatureHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEvent' example: id: 6630a1e2f4b1c9a0d3e4f5a8 event: upload.deleted createdAt: '2026-06-12T19:02:44Z' resource: type: upload id: 6a2c4da45f00109e85f1b15e customerId: 6a2bd5b71b1e7e575738920c data: changeType: Deleted responses: '200': description: Acknowledge receipt with any 2xx status. download.created: post: tags: - webhooks summary: download.created description: Sent when a download is created on your account. operationId: webhookDownloadCreated parameters: - $ref: '#/components/parameters/WebhookEventHeader' - $ref: '#/components/parameters/WebhookDeliveryHeader' - $ref: '#/components/parameters/WebhookSignatureHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEvent' example: id: 6630a1e2f4b1c9a0d3e4f5b1 event: download.created createdAt: '2026-06-12T18:45:10Z' resource: type: download id: 6a2c4e0b5f00109e85f1b160 customerId: 6a2bd5b71b1e7e575738920c data: changeType: Created responses: '200': description: Acknowledge receipt with any 2xx status. download.updated: post: tags: - webhooks summary: download.updated description: Sent when a download changes, for example when its status or transfer progress changes. operationId: webhookDownloadUpdated parameters: - $ref: '#/components/parameters/WebhookEventHeader' - $ref: '#/components/parameters/WebhookDeliveryHeader' - $ref: '#/components/parameters/WebhookSignatureHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEvent' example: id: 6630a1e2f4b1c9a0d3e4f5b2 event: download.updated createdAt: '2026-06-12T19:10:33Z' resource: type: download id: 6a2c4e0b5f00109e85f1b160 customerId: 6a2bd5b71b1e7e575738920c data: status: Completed changeType: Updated responses: '200': description: Acknowledge receipt with any 2xx status. download.deleted: post: tags: - webhooks summary: download.deleted description: Sent when a download is deleted. operationId: webhookDownloadDeleted parameters: - $ref: '#/components/parameters/WebhookEventHeader' - $ref: '#/components/parameters/WebhookDeliveryHeader' - $ref: '#/components/parameters/WebhookSignatureHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEvent' example: id: 6630a1e2f4b1c9a0d3e4f5b3 event: download.deleted createdAt: '2026-06-12T19:22:05Z' resource: type: download id: 6a2c4e0b5f00109e85f1b160 customerId: 6a2bd5b71b1e7e575738920c data: changeType: Deleted responses: '200': description: Acknowledge receipt with any 2xx status.