Find videos this ad fits into (NDJSON stream)
POST/api/v1/ads/match
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.
Response is application/x-ndjson (one JSON object per line), not a single JSON document. Parse line-by-line.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 500
Successful Response
Missing or invalid API key. Add Authorization: Bearer vuf_live_<keyid>.<secret>.
Key used outside the public API roots (/api/v1, /api/v1.1).
Referenced resource (video / job / ad) not found.
Request body failed validation.
Upstream service error — usually safe to retry.