Skip to content

API Documentation

Jump to bottom
Viren070 edited this page Jan 8, 2026 · 11 revisions

Base Path: /api/v1

/search

The /search endpoint lets you search for media content (movies, series, anime, etc.) across all enabled and configured sources in your AIOStreams instance.

Query Parameters

Name Type Required Description Example
type string Yes Type of content to search for. Any string that upstream addons will support, usually only movie and series movie
id string Yes ID of the media, including season/episode (TMDb, IMDb, or other supported identifier). tt1234567, tmdb:2131:1:3
requiredFields string[] | string No A list of fields from SearchApiResult that are required. Results without this field will be removed. To provide multiple fields, provide the requiredFields parameter multiple times e.g. requiredFields=infoHash&requiredFields=seeders infoHash

Authentication

You must authenticate your request by one of the following methods:

1. Basic Authentication

  • Use the Authorization header with the Basic scheme.
  • Username: your user UUID
  • Password: your user password
  • Example: 
    Authorization: Basic <base64(uuid:password)>

Unauthenticated Requests

Alternatively, you can provide the x-aiostreams-user-data header.

Note

While you don't need to create a user beforehand, if this instance is password protected, the addonPassword field is still required.

  • Add the header x-aiostreams-user-data with a base64-encoded UserData object.
  • UserData can be exported from the config page.
  • See the UserData schema here.

Response

Returns a JSON object with the following structure:

{
  "success": true,
  "detail": "Optional detail message",
  "error": null,
  "data": {
    "results": [
      /* Array of SearchResult objects */
    ],
    "errors": [
      {
        "title": "Error title",
        "description": "Detailed description of the error"
      }
    ]
  }
}

Top-level Properties

Name Type Description
success boolean true if the search was successful, otherwise false
detail string | null Optional detail message
error object | null Error object if the request failed
data object | null Data object containing results and any per-source errors
Error Object
Name Type Description
code string Machine-readable error code
message string Human-readable error message
Data Object
Name Type Description
results SearchResult[] Array of search results (see schema)
errors object[] List of errors that occurred during search

Example Request

GET /api/v1/search?type=movie&id=tt1234567 HTTP/1.1
Authorization: Basic bXktdXVpZDpteS1wYXNzd29yZA==
curl -u uuid:password "{baseUrl}/api/v1/search?type=movie&id=tt1234567"

or

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

Example Response

{
  "success": true,
  "detail": null,
  "error": null,
  "data": {
    "results": [
      {
        /* SearchResult object; [see schema](#schemas) */
      }
    ],
    "errors": []
  }
}

If an error occurs:

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

Schemas

Clone this wiki locally