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

> Explore the main API endpoints used by Stremio Web. This developer reference details communication with the backend for addons, catalogs, streams, search, and user profiles.

- Repository: [Stremio/stremio-web](https://github.com/Stremio/stremio-web)
- Tags: api-reference
- Published: 2026-05-23

---

**Stremio Web communicates with the Stremio backend through a centralized REST API layer defined in [`src/services/index.js`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/src/services/index.js)

Every **API endpoint** interaction flows through [`src/services/index.js`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/createTransport.ts) factory (located at [`src/core/createTransport.ts`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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:

```javascript
import services from '@/services';

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

```

Fetching a specific catalog:

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

```

Resolving stream URLs:

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

```

Performing global search:

```javascript
// 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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/useSubtitles.ts) and [`useStreamingOptions.ts`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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.