10

API Documentation

Viren070 edited this page 2025-10-26 19:52:27 +00:00

Table of Contents

• /search
• Query Parameters
• Authentication
• 1. Basic Authentication
• Unauthenticated Requests
• Response
• Top-level Properties
• Error Object
• Data Object
• Example Request
• Example Response
• Schemas

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. Supported values include: movie, series, anime, etc.	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

• UserData schema
• SearchResult schema

---