Submit a video

Submit a publicly fetchable video URL for transcoding.

POST /api/v1/streaming/video/submit

Submit a video URL to the streaming provider for transcoding. Returns immediately with status: 'pending'; a webhook follows when the asset is ready.

Scope

streaming:submit

Request

{
  "module": "properties",
  "entityId": "cm123abc456",
  "sourceUrl": "https://cdn.example.com/tours/abc.mp4",
  "callerRef": "your-row-id-optional"
}

Field	Type	Notes
`module`	string	Logical grouping inside your service (e.g. `properties`, `listings`, `errands`). Required.
`entityId`	string	The entity this video belongs to. Required.
`sourceUrl`	string	Publicly fetchable URL. Mux pulls the file itself; it does not see your service-auth headers. Required.
`callerRef`	string	Opaque correlation token. PlatformXe echoes this back on the webhook so you can match without a lookup. Optional but recommended.

Validations performed before submit

Uses the shared media probe (POST /api/v1/media/probe, mode soft) — same implementation as strict pre-register checks, but network blips are non-fatal so Mux can still try.

URL shape — must be http:// or https://.
HEAD + size + magic-byte sniff (when reachable) — may return:
- SOURCE_UNREACHABLE if the URL returns 4xx/5xx (strict mode only)
- SOURCE_TOO_SMALL if the file is under 64 KB
- SOURCE_NOT_VIDEO if Content-Type or container sniff fails
Deduping — pass sourceProbed: true on storage register / streaming submit when the caller already ran strict probe (e.g. Lettings after POST /api/v1/media/probe) to skip a second fetch.

Response

{
  "success": true,
  "data": {
    "id": "ply7tj9k6xq3v",
    "callerService": "lettings",
    "module": "properties",
    "entityId": "cm123abc456",
    "sourceUrl": "https://cdn.example.com/tours/abc.mp4",
    "callerRef": "your-row-id-optional",
    "muxAssetId": "uW3kQbXyZ...",
    "muxPlaybackId": null,
    "durationSeconds": null,
    "status": "pending",
    "errorMessage": null,
    "submittedAt": "2026-05-20T16:00:00.000Z",
    "readyAt": null,
    "erroredAt": null
  }
}

status: 'errored' at submit time means PlatformXe couldn't reach Mux at all (missing credentials, network failure). Mux's asynchronous transcode failures arrive via webhook later.

Idempotency