---
title: "Search indexed transcript passages in exactly one channel or video"
method: GET
path: "/v1/library/search"
tags: ["Library"]
---

# Search indexed transcript passages in exactly one channel or video

`GET /v1/library/search`

## Request

- Base URL: `https://api.scripthaul.com`
- URL: `https://api.scripthaul.com/v1/library/search`
- Auth: HTTP bearer

Zero-credit BM25-ranked source-caption passages with timestamp watch URLs. Requires a Bearer API key and exactly one channel or video_id; the scope is applied during the index search. Channel membership requires confirmed public-listing provenance. A URL-only fetched video stays searchable by video_id until a listing confirms its channel; player metadata alone does not establish membership. ID-only membership records prior listing, not current public visibility, and survives the original 30-day expiry of titles and publication dates. No site-wide or cross-channel search. Queries support words, quoted phrases, and prefix terms only, up to 500 characters and 32 terms/phrases. Prefixes require at least three characters in the final word, including quoted phrase prefixes; shorter prefixes return 400 InvalidInput. Free allowance: 500 searches/key/UTC day; paid: 20,000. Repeated valid searches count. The daily allowance is enforced before upstream work; exhaustion returns 429 QuotaExceeded with Retry-After until 00:00 UTC. Normal key RPM also applies. Translation output is not indexed; coverage can lag cache delivery. Channel coverage is read from stored channel totals, without scanning the full video list or processing pending enumeration during search. API listing pages, RSS reads, indexing, coverage refreshes, and bounded background synchronization maintain the counters. Listings captured only through the free site can lag until synchronization.

## Query parameters

- `q` string, required
- `channel` string
- `video_id` string
- `limit` integer
- `offset` integer

## Response `200`

Ranked passages; an empty results array means no match in indexed captions, not complete coverage.

- LibrarySearch
  - `ok` unknown, required
  - `query` string, required
  - `channel` string, nullable, required
  - `video_id` string, nullable, required
  - `limit` integer, required
  - `offset` integer, required
  - `coverage` object, required
    - `indexed` integer, required
    - `known` integer, required
  - `results` object[], required
    - `video_id` string, required
    - `title` string, nullable, required
    - `published_at` string, nullable, required
    - `start` number, required
    - `end` number, required
    - `text` string, required
    - `snippet` string, required
    - `url` string, required

## Other responses

- `400`: InvalidInput: missing, conflicting, malformed, or unsupported parameters, including a prefix with fewer than three characters in its final word. Costs zero credits.
- `401`: Forbidden: a Bearer API key is missing, malformed, unknown, or revoked. Dashboard cookies cannot authenticate this endpoint. Costs zero credits.
- `403`: AccountFrozen or Forbidden: the account is frozen or the authenticated caller cannot use this route. Costs zero credits.
- `429`: QuotaExceeded: key RPM or daily library search allowance (500 free or 20,000 paid per key) exhausted. Repeated valid searches count. Daily exhaustion returns Retry-After until 00:00 UTC. Costs zero credits.
- `502`: UpstreamError: scoped search or coverage could not be read. Costs zero credits.
- `503`: ConfigurationError: the library database is unavailable. Costs zero credits.

---

[API](https://skmtc.dev/scripthaul/apis/scripthaul-api.md) · [All operations](https://skmtc.dev/scripthaul/apis/scripthaul-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scripthaul/apis/scripthaul-api/revisions/f476d69f4a6b?raw)