Probe media URL

Canonical pre-store validation for video URLs (HEAD, size, magic bytes).

POST /api/v1/media/probe

Single source of truth for “is this URL a real, fetchable video?” Used by Lettings before register, storage register, media ingest, and streaming submit (soft mode).

Scope

storage:upload

Request

{
  "sourceUrl": "https://cdn.example.com/tours/abc.mp4",
  "mode": "strict"
}

Field	Type	Notes
sourceUrl	string	Public http(s) URL. Required.
mode	"strict" | "soft"	Default strict. soft treats probe network errors as pass (for Mux handoff).

Response

Success (200) when the URL looks valid:

{
  "success": true,
  "data": { "ok": true, "container": "mp4" }
}

Failure (400) when validation fails. The failure never arrives as data: it uses the standard error envelope. error.code is always PROBE_FAILED, and the specific reason is in error.details.reason. details.httpStatus and details.contentType are included when the probe observed them.

{
  "success": false,
  "error": {
    "code": "PROBE_FAILED",
    "message": "sourceUrl is 1024 bytes — too small to be a valid video file",
    "details": { "reason": "SOURCE_TOO_SMALL" }
  }
}

A request without sourceUrl returns 400 with error.code BAD_REQUEST and no details.

Failure reasons (error.details.reason)

Reason	Meaning
INVALID_URL	Not parseable or not http(s)
SOURCE_UNREACHABLE	HEAD failed or non-2xx
SOURCE_TOO_SMALL	Under 64 KB
SOURCE_NOT_VIDEO	Wrong Content-Type or unknown container
SOURCE_UNREADABLE	Could not read bytes for sniff