Search

GET /api/v1/search

Search for streams across all enabled and configured sources in your AIOStreams instance. Results are processed through the same filtering and sorting pipeline as normal Stremio stream requests.

Query Parameters

Parameter	Type	Required	Description	Example
`type`	string	✅	Type of content — usually `movie` or `series`	`movie`
`id`	string	✅	Media ID. Supports IMDb, TMDb, and other upstream identifiers. For series, include season/episode.	`tt1234567`, `tmdb:2131:1:3`
`requiredFields`	string[]	❌	Fields from `SearchApiResult` that must be present. Results missing them are dropped. Repeat for multiple.	`requiredFields=infoHash&requiredFields=seeders`
`format`	string	❌	Response format. Use `stremio` to return a Stremio-compatible `streams` array instead of the default envelope.	`stremio`

User Data

To retrieve personalised streams from your configured addons, you must provide user data via one of two methods:

Basic Auth

Authorization: Basic <base64(uuid:password)>

curl -u uuid:password "https://your-instance.example.com/api/v1/search?type=movie&id=tt1234567"

User Data Header

Pass a base64-encoded UserData JSON object (exportable from the config page):

x-aiostreams-user-data: <base64(userDataJSON)>

If the instance is password-protected, the addonPassword field is still required in the UserData object.

Top-level Properties

Field	Type	Description
`success`	boolean	`true` if the search succeeded
`detail`	string \| null	Optional detail message
`error`	object \| null	Error object if the request failed
`data`	object \| null	Data object containing results

Error Object

Field	Type	Description
`code`	string	Machine-readable error code (e.g. `BAD_REQUEST`)
`message`	string	Human-readable error message

Data Object

Field	Type	Description
`results`	SearchResult[]	Array of search results
`errors`	object[]	Per-source errors that occurred during search

Each error in errors has:

title — short error title
description — detailed description

Error Response Example

Example Requests

Movie by IMDb ID (Basic Auth):

GET /api/v1/search?type=movie&id=tt1234567 HTTP/1.1
Authorization: Basic bXktdXVpZDpteS1wYXNzd29yZA==

curl -u uuid:password "https://your-instance.example.com/api/v1/search?type=movie&id=tt1234567"

Series with Stremio-format response:

GET /api/v1/search?type=series&id=tmdb:2131&format=stremio HTTP/1.1
x-aiostreams-user-data: eyJ1c2VySWQiOiAiYWJjZCIsICJwYXNzd29yZCI6ICJzZWNyZXQifQ==

Response

Default

{
  "success": true,
  "detail": null,
  "error": null,
  "data": {
    "results": [
      /* SearchResult[] */
    ],
    "errors": []
  }
}

Data Object

Field	Type	Description
`results`	SearchResult[]	Filtered and sorted stream results
`errors`	object[]	Per-source errors (`title` + `description`)

`format=stremio`

Returns a Stremio-compatible response with a streams array instead of the normal envelope.

Error Response

{
  "success": false,
  "detail": null,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid credentials"
  },
  "data": null
}

Schemas

UserData schema — the JSON object encoded in x-aiostreams-user-data
SearchResult schema — the shape of each result in data.results

On this page