# Stremio Addon Aggregator API Reference

## Endpoint URLs

All Stremio addons follow the same protocol format:
```
{base_url}/stream/{type}/{id}.json
```

| Addon | Base URL | Type Values |
|-------|----------|-------------|
| **Torrentio** | `https://torrentio.strem.fun` | movie, series |
| **Comet** | `https://comet.elfhosted.com` | movie, series |
| **MediaFusion** | `https://mediafusion.elfhosted.com` | movie, series |

## Response Format

All addons return the same Stremio stream response format:

```json
{
  "streams": [
    {
      "name": "Torrentio RD",
      "infoHash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
      "fileIdx": 0,
      "title": "1080p - Movie Name (2024) [4K] | 1.5GB",
      "behaviorHints": {
        "cached": true,
        "notWebReady": false,
        "bingeGroup": "torrentio-...",
        "filename": "..."
      }
    }
  ]
}
```

## Parsing Logic

In `BaseAddonAggregator.parse_stream_to_result()`:
1. Extract `infoHash` — must be a non-empty string. Reject if missing/not a string.
2. Lowercase the hash.
3. Construct magnet URL: `magnet:?xt=urn:btih:{info_hash}`
4. Extract `title` for user-facing display.
5. Try to extract seeds from `behaviorHints.seeds` / `behaviorHints.seeders` / `behaviorHints.seedcount`.
6. Return `TorrentSearchResult(info_hash=..., magnet_url=..., title=..., seeds=..., source="torrentio"|"comet"|"mediafusion")`

## Deduplication

`AggregatorSearchService` queries all 3 aggregators × both content types (movie + series) = **6 concurrent requests** via `asyncio.gather`.

Deduplication by `info_hash` — keep the entry with the highest seed count. Sort final list by seeds descending, cap at 100 results.

## Error Handling

- Any aggregator failure (timeout, non-200, malformed JSON) → log warning, return empty list for that aggregator
- Individual failure never kills the whole search
- 2 attempts on 502/503/504 (retryable status codes)
- Timeout: connect=5s, read=10s

## Cloudflare Bypass

**Critical — without this, all aggregators silently fail with 403.**

Public Stremio addon APIs (Torrentio, Comet on ElfHosted, MediaFusion on ElfHosted) use Cloudflare. The default `httpx` User-Agent (`python-httpx/0.x.x`) gets blocked immediately.

Fix: Set a browser-like User-Agent on the `httpx.AsyncClient`:

```python
_DEFAULT_HEADERS = {
    "User-Agent": (
        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
        "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
    ),
    "Accept": "application/json",
}
```

Torrentio accepts this UA and returns 200. Comet and MediaFusion on ElfHosted may still 403 — they use more aggressive Cloudflare configs. As of May 2026, Torrentio is the most reliable of the three from a bare httpx client. The aggregator handles this gracefully (logs warning, returns empty, other aggregators fill in).

## Build Note: URL Format

The Stremio addon URL format is `{base_url}/stream/{type}/{id}.json` (note the `/stream/` prefix). This was initially implemented as `{base_url}/{type}/{id}.json` in the first version, which would 404. Caught by OpenCode Go (big-pickle) review.