Main API Endpoints Used by Stremio Web: A Complete Developer Reference

Stremio Web communicates with the Stremio backend through a centralized REST API layer defined in src/services/index.js, exposing endpoints for addons, catalogs, streams, metadata, search, user profiles, and settings.

The Stremio Web client (repository: Stremio/stremio-web) relies on a concise set of RESTful API endpoints to fetch content metadata, resolve streaming URLs, and manage user data. According to the source code, all network requests are orchestrated through a centralized service layer that constructs URLs and delegates HTTP transport to a dedicated fetch wrapper.

Centralized Service Architecture in src/services/index.js

Every API endpoint interaction flows through src/services/index.js. This module exports helper functions that construct endpoint URLs relative to a configurable base URL (set via the STREMIO_BACKEND_URL environment variable). The actual HTTP execution is handled by a transport object created in src/core/createTransport.ts, which wraps the browser's native fetch API with error handling and header management.

Complete List of Stremio Web API Endpoints

The main API endpoints used by Stremio Web are organized into four functional categories: addon management, content discovery, streaming resolution, and user configuration.

Addon Management Endpoints

These endpoints handle installed addon manifests and discovery.

• GET api/v2/addons – Retrieved via getAddons(). Returns the complete list of installed addons.
• GET api/v2/addons/:addonId – Retrieved via getAddon(addonId). Fetches the detailed manifest for a specific addon identified by its ID.

Content Catalog and Metadata Endpoints

Used for browsing catalogs and retrieving detailed information about movies or series.

• GET api/v2/catalog/:type/:id/:extra? – Retrieved via getCatalog(type, id, extra). Loads catalog items from a specific addon (e.g., movies from the YouTube addon). The optional extra parameter supports pagination and filtering.
• GET api/v2/meta/:type/:id – Retrieved via getMeta(type, id). Fetches rich metadata including title, description, poster images, and cast information for a specific item.
• POST api/v2/search – Triggered via search(query). Performs free-text search across all installed addon catalogs.

Streaming Resolution Endpoints

Responsible for resolving actual media URLs and subtitle tracks.

• GET api/v2/stream/:type/:id/:extra? – Retrieved via getStream(type, id, extra). Resolves streaming URLs and available subtitle tracks for a given content item, as consumed by components like src/routes/Player/useSubtitles.ts.

User Data and Settings Endpoints

Manage user profiles, library state, and application configuration.

• GET api/v2/user/profile – Retrieved via getUserProfile(). Loads the current user's profile data including library sync status and watch history.
• GET api/v2/user/library – Retrieved via getLibrary(). Returns the user's saved library items.
• GET api/v2/user/playlist – Retrieved via getPlaylists(). Fetches user-created playlists.
• GET / PATCH api/v2/settings – Read via getSettings(), updated via updateSettings(). Manages user preferences such as language and streaming quality, utilized by settings routes like src/routes/Settings/Streaming/useStreamingOptions.ts.

Transport Layer and Request Construction

All API endpoints are prefixed with the backend base URL defined in the environment. The createTransport.ts factory (located at src/core/createTransport.ts) instantiates the fetch wrapper used by the service layer. This architecture ensures consistent header application and error handling across the application. The same transport mechanism is reused for Chromecast-specific calls in src/services/Chromecast/ChromecastTransport.js, confirming the uniformity of the API surface.

Practical Implementation Examples

Here are concrete usage patterns from the Stremio Web codebase.

Loading installed addons:

import services from '@/services';

// Load all installed addons
services.getAddons().then(addons => {
  console.log('Installed addons:', addons);
});

Fetching a specific catalog:

// Fetch movie catalog from a specific addon
services
  .getCatalog('movie', 'stremio-addon-youtube')
  .then(catalog => console.log('Catalog items:', catalog));

Resolving stream URLs:

// Resolve stream for The Shawshank Redemption (tt0111161)
services
  .getStream('movie', 'tt0111161')
  .then(stream => console.log('Available streams:', stream));

Performing global search:

// Perform free-text search across all catalogs
services
  .search({ query: 'Inception' })
  .then(results => console.log('Search results:', results));

Summary

• Stremio Web consolidates all backend communication in src/services/index.js, providing a clean interface to REST endpoints including api/v2/catalog, api/v2/stream, and api/v2/user/library.
• The transport layer at src/core/createTransport.ts handles fetch mechanics and base URL resolution via the STREMIO_BACKEND_URL environment variable.
• Core endpoints cover four domains: addon management (api/v2/addons), content discovery (catalog, meta, search), streaming resolution (stream), and user data (user/profile, user/library, settings).
• Consistent patterns: All service functions return Promises that resolve to JSON data, consumed by React hooks in routes like useSubtitles.ts and useStreamingOptions.ts.

Frequently Asked Questions

How does Stremio Web handle API authentication?

Authentication tokens are injected at the transport layer in src/core/createTransport.ts. The transport adds required headers to each request, ensuring that user-specific calls to endpoints like api/v2/user/library carry valid session credentials automatically without manual header construction in component code.

What is the difference between the meta and catalog endpoints?

The meta endpoint (api/v2/meta/:type/:id) returns detailed information for a single item (title, description, images), while the catalog endpoint (api/v2/catalog/:type/:id) returns a list of items from a specific addon's catalog. Code in src/services/index.js distinguishes these by their function signatures: getMeta(type, id) versus getCatalog(type, id, extra).

Can I use these endpoints outside of the Stremio Web application?

Yes. While src/services/index.js provides a convenient JavaScript wrapper, the underlying REST endpoints can be called directly with standard HTTP clients such as curl or Postman. You must provide the appropriate base URL and authentication headers as defined in the transport configuration to access protected resources like api/v2/user/profile.

How are stream URLs resolved for different content types?

The getStream() function in src/services/index.js constructs requests to api/v2/stream/:type/:id, where type can be "movie", "series", or other content identifiers. The optional extra parameter handles season/episode numbers for series. The backend resolves available sources, returning an array of stream objects that include the actual playback URL, quality metadata, and subtitle track information.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}