Search

An optional catalog-wide search endpoint, returning the same video summaries as a collection listing.

Advertise the search keyword in your manifest'scapabilities to mount this route. No user identity is ever required.

GET/search?q={query}

The response has the exact shape ofa collection's items listing —items plus next_cursor — so clients reuse their summary rendering as-is. Match on title and tags at minimum; fuzzier matching is up to you.

curl "https://api.example.com/vcp/v1/search?q=arrival&limit=25" \
  -H "VCP-Service-Token: vcps_a81f42..."

import requests

API = "https://api.example.com/vcp/v1"
HEADERS = {"VCP-Service-Token": "vcps_a81f42..."}

resp = requests.get(f"{API}/search",
                    params={"q": "arrival", "limit": 25}, headers=HEADERS)
resp.raise_for_status()

for item in resp.json()["items"]:
    print(item["id"], item["title"])

require "rest-client"
require "json"

API = "https://api.example.com/vcp/v1"
HEADERS = { "VCP-Service-Token" => "vcps_a81f42..." }

resp = RestClient.get("#{API}/search",
                      HEADERS.merge(params: { q: "arrival", limit: 25 }))

JSON.parse(resp.body)["items"].each do |item|
  puts "#{item["id"]}  #{item["title"]}"
end

const API = 'https://api.example.com/vcp/v1'
const HEADERS = { 'VCP-Service-Token': 'vcps_a81f42...' }

const url = new URL(API + '/search')
url.searchParams.set('q', 'arrival')
url.searchParams.set('limit', 25)

const resp = await fetch(url, { headers: HEADERS })
if (!resp.ok) throw new Error('VCP request failed: ' + resp.status)

const { items } = await resp.json()
for (const item of items) console.log(item.id, item.title)

200 OK

{
  "items": [
    {
      "id": "vid_88213",
      "title": "Episode 1 - Arrival",
      "duration": 1440,
      "thumbnail_url": "https://cdn.example.com/thumbs/88213.jpg",
      "updated_at": "2026-06-28T08:11:00Z"
    }
  ],
  "next_cursor": null
}

Remember that search queries are untrusted client-supplied input — treat them like any other, especially if they end up rendered on your website (see theprovider checklist).