ytsearch API docs

The ytsearch API is public and read-only. It needs no key: send an HTTP GET and read JSON. The machine-readable contract is the OpenAPI document, and llms.txt tells agents when to use it.

Quickstart

curl 'https://search.experimental.pronsh.dev/api/v1/search?q=server+actions&youtuber=%40theo&per_page=3'

Each video in videos has a youtube_url and hits; every hit is a transcript moment with its text and a youtube_url that opens at that timestamp.

Endpoints

Endpoint	Use
`GET /api/v1/search`	Find transcript moments, grouped by video.
`GET /api/v1/youtubers`	List indexed creators and their video counts.
`GET /api/v1/availability`	Check whether search is serving.
`GET /api/v1/health`	Check that the API can reach its index.

Search parameters

Name	Meaning
`q`	Required. Words to find; quote a phrase to match it exactly.
`youtuber`	Only this creator, such as `@theo`.
`video_id`	Only this video, to list its moments.
`sort`	`relevance` (default), `relevance_engagement`, `views_desc`, `likes_desc`, `comments_desc`, `published_desc` or `published_asc`.
`page`, `per_page`	Paging; results are grouped by video.
`mode`	`lexical` (default) or, where it is hosted, `hybrid` or `semantic`. The response's `mode` says which actually answered.

Authentication and limits

No authentication, API key or OAuth flow exists. Search allows about 120 requests a minute per IP address; search responses state this in RateLimit-Policy, and beyond it you get 429 and should wait before retrying. Please do not bulk-export the index.

Versioning

The path carries the major version. Additive changes, such as new response fields, stay in /api/v1; a breaking change gets /api/v2, and /api/v1 keeps working until its deprecation is announced on this page.

Errors

Errors are JSON: {"error": "what went wrong", "code": "stable_code", "hint": "what to do"}. 400 means fix the request, 404 means no such route, 429 means slow down and 503 means retry shortly.

Sharing a moment

A link such as /s/VIDEO_ID?t=754&end=784&q=server+actions opens a page with that window of the video and the matching transcript lines. Request it with Accept: text/markdown to get the same page as Markdown; every page here does the same.