Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.discovr.media/llms.txt

Use this file to discover all available pages before exploring further.

When you build a streaming app, users need a way to find titles they’re looking for—by name, actor, or keyword. The search endpoint lets you wire up a search experience in minutes.

​
Make a search request

Call searchMedia() with a query string. The SDK returns paginated results with movies, TV shows, and cast members mixed together. 
import { DiscovrClient } from "discovr";

const client = new DiscovrClient("your-client-id");
const results = await client.searchMedia({ query: "blade runner" });

console.log(results.results);
// [
//   { id: "MV_550", title: "Blade Runner", media_type: "movie", ... },
//   { id: "TV_1234", title: "Blade Runner: Black Lotus", media_type: "tv", ... },
//   { id: "PERSON_5678", name: "Ryan Gosling", media_type: "person", ... }
// ]
Search requires an active profile session. If you haven’t selected a profile yet, start with selectProfile() first. The search results themselves are the same for all profiles—personalization happens later when you fetch the detail view.

​
Handle result types

Search results mix three types: media (movies and TV shows) and person (cast and crew). Each has a different shape, so you’ll need to handle them differently in your UI. Media results have:
  • id — Unique media ID (prefixed with MV_ for movies, TV_ for shows)
  • title — Movie or show name
  • media_type — Either "movie" or "tv"
  • poster_path — Thumbnail URL for rendering
Person results have:
  • id — Prefixed with PERSON_
  • name — Actor or creator name
  • media_type — Always "person"
  • profile_path — Headshot URL (optional)
for (const result of results.results) {
  if (result.media_type === "person") {
    // Render person card: name + headshot
    console.log(`${result.name} (${result.media_type})`);
  } else {
    // Render media card: title + poster
    console.log(`${result.title} (${result.media_type})`);
  }
}

​
Pagination

Results are paginated. The response includes page, total_pages, and total_results. Request the next page with the page parameter. 
// Page 1 (default)
const page1 = await client.searchMedia({ query: "matrix", page: 1 });
console.log(`Showing ${page1.results.length} of ${page1.total_results}`);

// Page 2
const page2 = await client.searchMedia({ query: "matrix", page: 2 });

​
Render and navigate

After the user taps a result, handle media and person results differently: For media results: Open the detail view. Fetch the full media object with getMedia() and build your detail sheet (synopsis, cast, similar titles). For person results: You can navigate to the person’s page if your app has one, or show a simple bio. For now, you might redirect to a cast/crew grid or just show their name. 
async function handleResultTap(result: SearchResult) {
  if (result.media_type === "person") {
    // Navigate to person's profile or show bio
    console.log(`Tapped ${result.name}`);
    return;
  }

  // Fetch full media details
  const media = await client.getMedia(result.id);
  console.log(media.overview); // Open detail sheet with this data
}

​
Handle empty results

If the user’s query returns no results, results will be an empty array. Show a friendly message like “No results found. Try a different search.” If the query is too short (less than 1 character) or invalid, the SDK will return a validation error. Catch it and show a helpful message. 
try {
  const results = await client.searchMedia({ query });
  
  if (results.results.length === 0) {
    console.log("No titles found for that search");
    return;
  }
  
  // Render results
} catch (error) {
  console.error("Search failed:", error.message);
}

​
Put it together: Full search flow

Here’s a complete search-to-detail example: 
import { DiscovrClient } from "discovr";

const client = new DiscovrClient("your-client-id");

async function runSearch(query: string) {
  // Search
  const results = await client.searchMedia({ query });
  console.log(`Found ${results.results.length} results`);

  // Tap the first result
  if (results.results.length > 0) {
    const firstResult = results.results[0];
    
    if (firstResult.media_type === "media") {
      // Open detail view
      const media = await client.getMedia(firstResult.id);
      console.log(`Title: ${media.title}`);
      console.log(`Description: ${media.overview}`);
    }
  }
}

runSearch("inception");
  • Media details — After a search result tap, fetch the full media object and show cast, seasons, and similar titles
  • Profile context — When building your detail view, fetch personalized overlays (watchlist status, resume position) to show the right buttons
  • Browse recommendations — For users who don’t know what to search for, show pages and recommendation rows as an alternative discovery path
API Reference: Search media and persons