# StableMedia API Reference

Pay-per-request access to the Streaming Availability API (Movie of the Night).
Coverage: 60+ countries, 200+ streaming services. Scope: shows, countries,
genres.

## Authentication

All endpoints require micropayment per the HTTP 402 specification. Payments
settle on Base mainnet (eip155:8453) or Solana.

## Base URL

https://stablemedia.dev

## Agent Workflow

1. Discover endpoints with `mcp__agentcash__discover_api_endpoints("https://stablemedia.dev")`.
2. Call `mcp__agentcash__check_endpoint_schema` before first fetch.
3. Execute with `mcp__agentcash__fetch`.

## Response size knobs

Responses default to a lean shape. Heavy fields are opt-in via boolean flags:

- `include_images` (shows, countries — default false) — adds poster/backdrop and service-logo imageSet URLs. Roughly +70% payload.
- `include_audio_subtitles` (shows — default false) — adds per-option `audios[]` and `subtitles[]` arrays.
- `include_addons` (countries — default false) — adds `services[].addons[]` (Apple-TV Channels etc). Roughly +80% payload on `countries/list`.

Omit the flags (or pass `false`) for the smallest response that still answers "where can I stream X?". Turn them on only when you need the specific fields for a UI or for locale matching.

---

# Shows

## POST /api/shows/search-title
Search for movies or series by title in a specific country.
Price: $0.01 per request

Example:
```json
{
  "country": "us",
  "title": "stranger things",
  "show_type": "series"
}
```

Parameters:
- `country` (string, required) — ISO 3166-1 alpha-2 code (e.g. "us", "gb")
- `title` (string, required) — Title to search for
- `show_type` (string, optional) — "movie" or "series"
- `series_granularity` (string, optional) — "show", "season", or "episode"
- `output_language` (string, optional) — ISO 639-1 language code

---

## POST /api/shows/search-filters
Advanced catalog search with filters (catalogs, genres, year, rating, etc.).
Price: $0.01 per request

Example:
```json
{
  "country": "us",
  "catalogs": "netflix",
  "show_type": "movie",
  "genres": "drama",
  "order_by": "popularity_1year"
}
```

Parameters:
- `country` (string, required) — ISO 3166-1 alpha-2 code
- `catalogs` (string, optional) — comma-separated service IDs, e.g. "netflix,prime"
- `show_type` (string, optional) — "movie" or "series"
- `genres` (string, optional) — comma-separated genre IDs
- `genres_relation` (string, optional) — "and" or "or" (default "and")
- `show_original_language` (string, optional) — ISO 639-1 code
- `year_min`, `year_max` (integer, optional)
- `rating_min`, `rating_max` (integer 0-100, optional)
- `keyword` (string, optional)
- `series_granularity` (string, optional)
- `order_by` (string, optional) — e.g. "original_title", "popularity_1year", "rating", "release_date"
- `order_direction` (string, optional) — "asc" or "desc"
- `cursor` (string, optional) — pagination token from a previous response
- `output_language` (string, optional)

---

## POST /api/shows/get
Get details for a single show by internal ID, IMDb ID (tt-format), or TMDB ID
(movie/tv format).
Price: $0.01 per request

Example:
```json
{
  "id": "6",
  "country": "us"
}
```

Parameters:
- `id` (string, required)
- `country` (string, optional) — include streaming availability for this country
- `series_granularity` (string, optional)
- `output_language` (string, optional)

---

## POST /api/shows/top
Top shows for a specific service in a country. Supported services: netflix,
prime, disney, apple, hbo.
Price: $0.01 per request

Example:
```json
{
  "country": "us",
  "service": "netflix",
  "show_type": "series"
}
```

Parameters:
- `country` (string, required)
- `service` (string, required) — service ID
- `show_type` (string, optional) — "movie" or "series"
- `output_language` (string, optional)

---

# Countries

## POST /api/countries/list
List every supported country with its streaming services.
Price: $0.01 per request

Example:
```json
{}
```

---

## POST /api/countries/get
Get a single country's details and available services.
Price: $0.01 per request

Example:
```json
{
  "country_code": "us"
}
```

---

# Genres

## POST /api/genres/list
List all supported genres.
Price: $0.01 per request

Example:
```json
{}
```

---

# Pricing Summary

| Endpoint | Price |
|----------|-------|
| POST /api/shows/search-title   | $0.01 |
| POST /api/shows/search-filters | $0.01 |
| POST /api/shows/get            | $0.01 |
| POST /api/shows/top            | $0.01 |
| POST /api/countries/list       | $0.01 |
| POST /api/countries/get        | $0.01 |
| POST /api/genres/list          | $0.01 |