Paladin Addon Developer Guide

Welcome, developer! This guide provides everything you need to know to build and share your own addons for Paladin.

Paladin's addon system is designed to be open, simple, and secure. By creating an addon, you can add new content sources to Paladin, allowing users to find and stream content from anywhere on the web.

The core principle is simple: an addon is just a web API that responds to Paladin's requests. Your code never runs inside Paladin, ensuring a secure environment for users.

Legal Disclaimer

Important: Paladin and its developers are not responsible for the content, legality, or actions of third-party addons. Addons are created and maintained by independent developers, and Paladin cannot guarantee the legality or safety of the content they provide.

By developing or using addons, you acknowledge that:

You are solely responsible for ensuring your addon complies with all applicable laws and regulations
Paladin is not liable for any legal issues arising from addon usage
You should consult with legal professionals regarding copyright and content distribution laws in your jurisdiction

How It Works: A Quick Overview

The architecture is a straightforward client-server model:

Paladin (Client): When a user wants to search for content, Paladin sends a POST request to your addon's API endpoint.
Your Addon (Server): Your web server receives the request, performs its search logic (by scraping a site or querying another API), and returns a standardized JSON response containing the search results.
Communication: HTTP POST with JSON

That's it! You host the API, and Paladin handles the rest.

Architecture

Paladin (Client): Sends search requests to addons
Addon (Server): Web API that responds according to the defined contract
Communication: HTTP POST with JSON

Step 1: Create Your Addon Manifest (addon.json)

Every addon needs a manifest file named addon.json. This file acts as the addon's identity card, telling Paladin everything it needs to know about it. You must host this file at a public URL.

Example addon.json

{
  "id": "com.yourname.my-awesome-provider",
  "name": "My Awesome Provider",
  "author": "Your Name",
  "version": "1.0.0",
  "description": "An addon to find awesome content from Source X.",
  "logo": "https://path/to/your/logo.png",
  "updatedAt": "2025-09-14T12:00:00Z",
  "minPaladinVersion": "1.2.0",
  "type": "searcher",
  "endpoints": {
    "movie": "https://your-api.com/search/movie",
    "series": "https://your-api.com/search/series"
  }
}

Manifest Fields Explained

Field	Type	Required	Description
`id`	String	Yes	A unique ID for your addon in reverse domain name format (e.g., `com.yourname.addonname`).
`name`	String	Yes	The display name of your addon in the Paladin UI.
`author`	String	Yes	Your name or username.
`version`	String	Yes	The current version of your addon, following SemVer (MAJOR.MINOR.PATCH).
`description`	String	Yes	A short description of what your addon does.
`logo`	String	Yes	A direct URL to an image file (PNG/JPG) to be used as an icon.
`updatedAt`	String	Yes	The date of the last update in ISO 8601 format. Used for version tracking.
`minPaladinVersion`	String	No	The minimum version of Paladin required for your addon to function correctly.
`type`	String	Yes	The type of addon. Currently, only "searcher" is supported.
`endpoints`	Object	Yes	An object containing the API endpoints for your addon.
`endpoints.movie`	String	Yes	The full URL endpoint for movie searches.
`endpoints.series`	String	Yes	The full URL endpoint for series searches.

Step 2: Build Your API (for "searcher" type)

As a "searcher" addon, your API's job is to find .torrent files based on media information sent by Paladin.

The Request from Paladin

Paladin will send a POST request to your endpoint with a JSON body.

Method: POST
Header: Content-Type: application/json

Request body for a movie:

{
  "type": "movie",
  "imdb_id": "tt1375666",
  "title": "Inception",
  "year": 2010
}

Request body for a series episode:

{
  "type": "series",
  "imdb_id": "tt0944947",
  "title": "Game of Thrones",
  "season": 1,
  "episode": 1
}

The imdb_id is the most reliable piece of information for matching content.

The Response Your API Must Send

Your API must respond with a 200 OK status and a JSON body containing a list of results. If no results are found, simply return an empty results array.

Response body format:

{
  "results": [
    {
      "name": "Inception 2010 1080p BluRay x264",
      "size": "2.2 GB",
      "seeders": 4500,
      "quality": "1080p",
      "torrentUrl": "https://source-x.com/torrents/inception-1080p.torrent"
    },
    {
      "name": "Inception (2010) 2160p 4K HDR",
      "size": "15.8 GB",
      "seeders": 1200,
      "quality": "4K",
      "torrentUrl": "https://source-x.com/torrents/inception-4k.torrent"
    }
  ]
}

Result Object Fields Explained

Field	Type	Required	Description
`name`	String	Yes	The full name of the torrent result.
`size`	String	Yes	The file size as a human-readable string (e.g., "1.5 GB", "850 MB").
`seeders`	Integer	Yes	The number of seeders. This helps users choose a healthy torrent.
`quality`	String	Yes	The video quality (e.g., "4K", "1080p", "720p", "SD").
`torrentUrl`	String	Yes	Crucial: This must be a direct download URL to the .torrent file. Do not use magnet links or web page URLs.

How Users Install Your Addon

Installation is simple and decentralized:

You build your addon and host the addon.json file and the API on your own server or a serverless platform.
You share the public URL of your addon.json file.
A user copies this URL and pastes it into the Addon Manager in Paladin to install it.

Usage in Paladin

Installation: Addons → Add the manifest URL
Activation: Toggle on/off in the addon list
Search: Automatic widget on pages for unowned media

Best Practices

Use HTTPS: Always serve your API and manifest file over HTTPS to protect user privacy and data integrity.
Be Fast: Users expect quick results. Optimize your search logic and consider caching responses on your end to improve performance.
Provide Quality Data: Ensure the data you return (especially seeders and quality) is as accurate as possible.
Handle Errors Gracefully: If an error occurs on your server, respond with an appropriate HTTP error code (e.g., 500). If no results are found, respond with 200 OK and an empty results array.

Implemented Features

✅ Addon management (add/remove/activation)
✅ Manifest validation
✅ Integrated search interface
✅ Movie and series support
✅ Automatic torrent downloads
✅ Error handling and timeouts
✅ Cache and persistent state

What's Next? Future Addon Types

The addon system is built to evolve. In the future, we plan to support new addon types, such as:

subtitles: To fetch subtitles for movies and series.
metadata: To provide alternative metadata and artwork.

Stay tuned for more ways to contribute!

Examples of Addons

Here are some examples of addon types you could create:

Public Site Scraper: Search on open trackers
Database API: Integration with third-party services
Multi-Source Aggregator: Combine multiple sources
Genre Specialist: Anime, documentaries, etc.

Security

HTTPS communication required
Strict manifest validation
Complete addon isolation
No direct access to the user's system

getpaladin/create-addon