Version: v1

YAHO API reference

The YAHO Public API — video indexing, semantic search, ad matching, and brand-safety screening over an indexed video corpus.

Authentication

Every /api/v1/* call requires an API key passed in the Authorization header:

Authorization: Bearer vuf_live_<keyid>.<secret>

Keys are issued from the dashboard's API Keys tab. The plaintext secret is shown once at creation and never recoverable — store it safely.

On each endpoint page, paste the key into the Authorization field of the request panel; it is sent with every request you make from that page.

Errors

Almost all 4xx/5xx responses share the same envelope:

{ "detail": "human-readable message",
  "code":   "optional.stable.code" }

code is present when the failure has a stable machine-readable reason and absent otherwise, so branch on its presence rather than assuming it. Sheet parse failures on POST /api/v1/videos/batch/upload-sheet (413 and 422) carry one extra sibling key: a rejected row count, when code is no_valid_urls.

Every endpoint below returns detail as a string in this envelope. Still branch on its type before reading it. Schema validation returns the array form covered next; a downstream body the gateway cannot interpret is relayed as-is rather than guessed at; and an error raised outside the API surface (an edge proxy, for example) can reach you as an opaque body carrying no envelope at all.

One code is produced by the gateway itself rather than the failing service: upstream_error_too_large means a downstream error body was too large to relay, so the status code is preserved but the per-item reasons are gone. Retry with fewer items to get the detailed response.

Separately, a request rejected by schema validation returns FastAPI's 422 list form — detail is an array of field errors ({"detail": [{"loc": …, "msg": …}]}) rather than the envelope above. This can come from any endpoint that declares a body; sending an over-length items array to POST /api/v1/videos/batch is the common case.

Common codes:

HTTP	Meaning
401	Missing / invalid API key.
403	Key used outside the public API roots (/api/v1, /api/v1.1).
404	Referenced video / job / ad not found.
422	Request body failed Pydantic validation.
500	Upstream service error — retry safe.

Quickstart

# 1. Submit a video for indexing
curl -X POST https://video.pyler.ai/api/v1/videos \
  -H "Authorization: Bearer $VUF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/clip.mp4"}'
# → { "video_id": "...", "job_id": "..." }

# 2. Wait for the job to finish
curl https://video.pyler.ai/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $VUF_API_KEY"
# → { "status": "done", ... }

# 3. Search across the corpus
curl -X POST https://video.pyler.ai/api/v1/search \
  -H "Authorization: Bearer $VUF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "child playing in snow", "modality": "both", "k": 10}'

Streaming endpoints

/api/v1/ads/match and /api/v1/videos/{video_id}/scenes/stream stream NDJSON (one JSON object per line) rather than returning a single JSON document, so partial results are usable while the multi-stage retrieval pipeline runs. Parse the response line-by-line.

Authentication

HTTP: Bearer Auth

Format: vuf_live_<keyid>.<secret>. Issued from the dashboard's API Keys tab; the plaintext is shown once.

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer