NewTube/api/README.md

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.