NewTube Unified Search API

This document describes the unified search endpoint used by the frontend SearchBar and Search page.

Base URL

Development: http://localhost:4000/api
Production: /api

Endpoint

GET /api/search

Query parameters

q (string, required, min length 2)
providers (string, optional): Comma-separated list of provider ids. Allowed values: yt, dm, tw, pt, od, ru. Defaults to all when omitted or invalid.
page (integer, optional): Page index starting at 1. Default: 1.
pageSize (integer, optional): Page size, max 50. Default: 24.
sort (string, optional): Reserved for future use.

Response

{
  "q": "string",
  "providers": ["yt", "dm", "tw", "pt", "od", "ru"],
  "groups": {
    "yt": [
      { "id": "string", "title": "string", "thumbnail": "string", "uploaderName": "string", "url": "string", "type": "video" }
    ],
    "dm": [],
    "tw": [],
    "pt": [],
    "od": [],
    "ru": []
  },
  "page": 1,
  "pageSize": 24
}

Error responses

400 { error: "invalid_query", details: "min_length_2" }
500 { error: "search_failed", details: "..." }

Providers

yt: YouTube
dm: Dailymotion
tw: Twitch
pt: PeerTube
od: Odysee
ru: Rumble

Notes

Each provider is queried in parallel with a per-provider limit equal to pageSize.
The endpoint currently does not expose a total field; the frontend should offer a simple Next page affordance or infinite scroll when appropriate.
Future: support for sort.