Overview
Addons provide resources through well-defined request/response patterns. Each resource type serves a specific purpose in the Stremio ecosystem.
Resource Response
All addon responses use the ResourceResponse enum:
pub enum ResourceResponse {
Metas { metas: Vec<MetaItemPreview> },
MetasDetailed { metas_detailed: Vec<MetaItem> },
Meta { meta: MetaItem },
Streams { streams: Vec<Stream> },
Subtitles { subtitles: Vec<Subtitles> },
Addons { addons: Vec<Descriptor> },
}
Responses must contain exactly one of these fields. Multiple fields or missing fields will cause deserialization errors.
Cache Control
Responses can include cache hints:
{
"streams": [...],
"cacheMaxAge": 3600,
"staleRevalidate": 14400,
"staleError": 604800
}
Seconds to cache the response. Sets Cache-Control: max-age=.
Seconds to serve stale content while revalidating. Sets Cache-Control: stale-while-revalidate=.
Seconds to serve stale content on error. Sets Cache-Control: stale-if-error=.
Catalog Resource
Provides lists of content items for browsing.
Request
GET /catalog/{type}/{id}/{extra}.json
type: Content type (e.g., movie, series)id: Catalog identifier from manifestextra: Optional query parameters (e.g., genre=Action&skip=100)
Response
{
"metas": [
{
"id": "tt1254207",
"type": "movie",
"name": "Big Buck Bunny",
"poster": "https://example.com/poster.jpg",
"posterShape": "poster",
"background": "https://example.com/bg.jpg",
"logo": "https://example.com/logo.png",
"description": "A large rabbit...",
"releaseInfo": "2008",
"runtime": "10 min",
"links": [],
"trailerStreams": [],
"behaviorHints": {}
}
]
}
Unique identifier for the item (e.g., IMDb ID tt1254207).
Content type: movie, series, tv, channel, etc.
Display name of the item.
Brief description or plot summary.
Release year or date information.
Duration information (e.g., "120 min", "2h 30m").
Shape of the poster: poster (default), square, or landscape.
External links (IMDb, genres, etc.).
Trailer streams for the item.
Hints about item behavior.
Request
GET /meta/{type}/{id}.json
Response
{
"meta": {
"id": "tt0944947",
"type": "series",
"name": "Game of Thrones",
"poster": "https://example.com/poster.jpg",
"background": "https://example.com/bg.jpg",
"description": "Nine noble families...",
"releaseInfo": "2011-2019",
"posterShape": "poster",
"links": [],
"trailerStreams": [],
"behaviorHints": {
"defaultVideoId": "tt0944947:1:1",
"hasScheduledVideos": false
},
"videos": [
{
"id": "tt0944947:1:1",
"title": "Winter Is Coming",
"released": "2011-04-17T00:00:00Z",
"overview": "Eddard Stark is torn...",
"thumbnail": "https://example.com/thumb.jpg",
"season": 1,
"episode": 1,
"trailerStreams": [],
"streams": []
}
]
}
}
All preview fields (see Catalog Resource).
Episodes, movies, or other playable content.
Video Fields
Unique video identifier. For series: {seriesId}:{season}:{episode}.
Season number (for series).
Episode number (for series).
Pre-attached streams for this video.
Stream Resource
Provides playable video sources.
Request
GET /stream/{type}/{id}.json
GET /stream/series/{seriesId}:{season}:{episode}.json
Response
{
"streams": [
{
"url": "https://example.com/video.mp4",
"name": "1080p",
"description": "High quality stream",
"thumbnail": "https://example.com/thumb.jpg",
"subtitles": [],
"behaviorHints": {
"notWebReady": false,
"bingeGroup": "example-group"
}
},
{
"infoHash": "24c8802e2624e17d46cd555f364debd949f2c81e",
"fileIdx": 0,
"announce": [
"udp://tracker.example.com:80"
],
"name": "Torrent 1080p",
"behaviorHints": {}
}
]
}
Stream Structure
Display name for the stream (e.g., quality, provider).
Additional information about the stream.
Embedded subtitle tracks.
Playback hints and metadata.
Stream Sources
URL Stream
{
"url": "https://example.com/video.mp4"
}
Torrent Stream
{
"infoHash": "24c8802e2624e17d46cd555f364debd949f2c81e",
"fileIdx": 0,
"announce": ["udp://tracker.example.com:80"],
"fileMustInclude": ["episode"]
}
20-byte torrent info hash (40 hex characters).
File index in the torrent. Omit for automatic selection.
Filename must contain these strings.
YouTube Stream
{
"ytId": "dQw4w9WgXcQ"
}
Archive Streams
For RAR, ZIP, 7ZIP, TAR, TGZ files:
{
"rarUrls": [
["https://example.com/file.rar", 10000],
["https://example.com/file2.rar"]
],
"fileIdx": 0,
"fileMustInclude": ["episode1"]
}
rarUrls, zipUrls, 7zipUrls, tarUrls, tgzUrls
External Stream
{
"externalUrl": "https://example.com/watch",
"androidTvUrl": "intent://...",
"tizenUrl": "tizen://...",
"webosUrl": "webos://..."
}
Player Frame
{
"playerFrameUrl": "https://example.com/embed/player"
}
Stream Behavior Hints
Stream is not playable in web browsers.
Identifier for grouping streams for binge-watching.
List of countries where stream is available.
Headers to use when proxying the stream.{
"request": {"Authorization": "Bearer token"},
"response": {"Access-Control-Allow-Origin": "*"}
}
Suggested filename for downloads.
Hash of the video content.
Video file size in bytes.
Subtitles Resource
Provides subtitle tracks.
Request
GET /subtitles/{type}/{id}.json
Response
{
"subtitles": [
{
"id": "en",
"lang": "eng",
"url": "https://example.com/subtitles/en.srt"
},
{
"id": "es",
"lang": "spa",
"url": "https://example.com/subtitles/es.vtt"
}
]
}
Subtitles Fields
Unique identifier for the subtitle track.
ISO 639-3 language code (e.g., eng, spa, fra).
Direct URL to the subtitle file (SRT, VTT, etc.).
Best Practices
Null Handling: The deserializer skips invalid items in arrays and treats null as empty arrays.
Error Responses: Invalid JSON or multiple response fields will cause deserialization errors.
Caching: Use cache headers to reduce server load and improve performance.
Video IDs: For series, use the format {seriesId}:{season}:{episode} for consistency.
