Suggestions
YouTube Suggestions API
Get YouTube autocomplete suggestions for a query so your agent can expand searches before it spends credits downstream.
Send a partial query and get YouTube autocomplete suggestions back as structured JSON. It is the lightweight way to expand a seed topic before running full search requests.
Agents can use suggestions to find adjacent topics, rewrite weak queries, build keyword lists, and decide which searches are worth running next.
Endpoint
GET https://api.stophy.dev/v1/suggest
1curl -G https://api.stophy.dev/v1/suggest \2 -H "Authorization: Bearer $STOPHY_API_KEY" \3 --data-urlencode "q=typescript"1{2 "query": "typescript",3 "suggestions": [4 "typescript tutorial",5 "typescript crash course",6 "typescript react",7 "typescript for beginners"8 ]9}What you can do
Fast query expansion
Turn one seed query into a list of YouTube-native autocomplete suggestions your agent can rank or search.
Cheap planning step
Use suggestions before search when an agent needs to explore a topic without guessing the exact query up front.
Pairs with search
Feed the best suggestions into /v1/search, then fetch transcripts, comments, or channel context for the winners.
Common use cases
- Expand a vague topic into concrete YouTube searches
- Build keyword lists for a YouTube research agent
- Find adjacent creator, tutorial, and product queries
- Plan searches before fetching transcripts or comments
Frequently asked questions
- When should I use suggestions instead of search?
- Use suggestions first when the agent has a seed topic but not the right YouTube query yet. Use search when you are ready to fetch actual videos, channels, or playlists.
- Does suggestions return videos?
- No. It returns autocomplete suggestions for the query. Send a suggestion into /v1/search to get videos, channels, playlists, or Shorts.
- How does this help agents?
- It gives the agent a planning step before heavier retrieval. The agent can expand a topic, pick the best query, then search and fetch deeper YouTube context.