# StreamSearch Up

StreamSearch Up helps people and AI agents find streaming availability for movies
and TV shows. No account, API key, JavaScript, or CAPTCHA is required for the
public read-only API. Do not request access to admin or write endpoints.

## Search API

Base path: /api on this website's origin.
Machine-readable OpenAPI contract: /agent-api.json

Automated clients should send this HTTP header on every request:
X-StreamSearch-Client: agent

An identifiable User-Agent such as StreamSearchAgent/1.0 is also recommended.
Known AI-agent User-Agents are recognized automatically. The explicit header
also works for agents that use a normal browser User-Agent.

Optional: send X-StreamSearch-Session with one opaque random identifier for an
entire search conversation. Reuse it for search and title lookups, and do not
put personal information into it. This improves the accuracy of the public
AI-agent session counter. Without it, network and User-Agent signatures are
used to estimate sessions. Counter requests themselves are not counted.

1. GET /api/countries
   Returns supported country codes and names. Ask the user for their country
   rather than assuming the United States.

2. GET /api/search?q=The%20Crow&country=US
   URL-encode the movie or TV title. Prefer at least two characters.
   Returns {"query":"The Crow","country":"US","results":[...]}.
   Up to 10 results include id, title, year, type, and sources.
   Originals and remakes are separate results; use the year and type to
   disambiguate them rather than silently choosing the newest version.

3. GET /api/title?id=1385504&country=US
   Looks up the chosen search result's Watchmode title ID, not its TMDB ID.
   Returns one title with the same fields and its streaming sources.
   Reuse an ID returned by search; do not guess IDs.

4. Optional actor lookup: GET /api/actor?name=Brandon%20Lee
   Returns {"titles":[{"id":1385504,"title":"The Crow","year":1994},...]}.
   Follow with the title endpoint for country-specific availability.

Example:
curl -H 'X-StreamSearch-Client: agent' \
  'https://streamsearchup.com/api/search?q=The%20Crow&country=US'

## Reading availability

Each source includes name, type, webUrl, format, price, seasons, and episodes.
Types: sub (subscription), free, rent, buy, and tve (TV-provider authentication).
Use the returned webUrl as supplied; eligible provider links may contain
affiliate tracking. A null webUrl means no destination link is available.
Some fallback links go to a TMDB availability guide, not directly to the provider.

Agent requests can search the full local title catalogue. They use cached
Watchmode links first, cached title availability next, or TMDB fallback on a
cache miss. Agents never trigger paid Watchmode refreshes.
Availability is a snapshot, not a guarantee of current pricing or access.
An empty sources list is not proof that a title is unavailable everywhere.
Do not claim that a subscription or purchase was completed: this API only
finds availability and links.

## Errors and request etiquette

400: invalid or missing query parameters, or an unsupported country.
404: unknown title ID on the title endpoint.
502: search or provider service temporarily unavailable; retry later.
Treat errors as errors, not as evidence that no titles exist.
Reuse results for repeated questions and avoid bulk enumeration or rapid retries.
Automated requests are excluded from human visitor and trending-search counts.

## Human-readable pages

- / — Search homepage
- /title/{slug}/{country} — Server-rendered title pages, no JavaScript required
- /how-it-works.html — Explanation of the service
- /faq.html — Frequently asked questions
- /about.html — About the site

## Sitemaps

- /sitemap.xml — Static pages
- /sitemap-titles.xml — Discovered title pages

## Data sources

Title discovery uses the local catalogue. Availability uses Watchmode with TMDB
fallback. Country coverage and provider coverage vary; /api/countries is the
current source of supported country codes.