Ads

Ad creative registry and matching.

📄️Find videos this ad fits into (NDJSON stream)

Given a registered creative (`ad_id`), stream back the scenes it fits into as NDJSON. Each line is a JSON object with a `type` field, in this order: `analyzing` (`stage` progress markers), `ad_analysis` (the creative's analysis — same fields as `GET /v1/ads/{ad_id}/analysis`), `agent_step` (query planning: `tool`, `query`, `ok`, `note`), `meta` (`facets`, `tags`, `brand_context`, `candidates` — the candidate scenes before rerank), one `result` per reranked scene (`video_id`, `video_title`, `scene_id`, `scene_index`, `score` 0–10, `reason`, `timestamp_ms` — absolute position in the video, `timestamp_sec_in_clip`, `scene_start_ms`, `scene_end_ms`, `clip_url`), then `done`. A failure is emitted as `error` (`message`) and ends the stream. `result` lines arrive as the rerank finishes, not sorted — order by `score` client-side, and ignore `type` values you do not recognise.

📄️Register ad creative (URL / VAST, async)

Register an ad creative from a media URL, or from a VAST tag URL / XML (Inline or Wrapper — the resolver unwraps it to the media). Returns immediately with `202` and `status: resolving`; a background resolver downloads and validates the media, then flips the record to `ready` (with `storage_path`, `duration_ms`) or `failed` (with `error`). Poll `GET /v1/ads/{ad_id}` for progress. The resulting `ad_id` is accepted by ad matching / blocking.

📄️List ad creatives

List your team's registered ad creatives, newest first. Each item carries `status` (`resolving` / `ready` / `failed`) and `source_type` (`file` / `url` / `vast_url` / `vast_xml`).

📄️Upload ad creative (file, sync)

Upload an ad video file (multipart). Stored synchronously — the response is already `status: ready` and the `ad_id` is immediately usable. Length cap: 120s.

📄️Get ad creative

Fetch one ad creative — also the polling endpoint for async registrations (`resolving` → `ready` / `failed`). Unknown ids and ads owned by another team both return `404`.

📄️Get ad creative analysis

What this creative is selling, who it targets, and how it reads on brand-safety axes — without running a match. Same values the `ad_analysis` event of `/v1/ads/match` carries.

📄️Stream a ready ad creative

Redirects (307) to a presigned URL for the stored ad file — point an HTML5 `<video>` at this directly. `409` if the ad isn't `ready` yet (no stored file to stream).