# 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`.