Hello, amazing Plex pros!!
While a Plex Media Server is powerful and awesome all on its own, occasionally server owners (like you) find themselves wanting more. In years past, this has been achieved through various means – one of the more popular methods was the ability to install plugins on your system. While that was popular, it was a system that became increasingly hard to support over time, and it was discontinued in 2018 (even though some users still ask about it to this day in the forums!).
In the interim, it has possibly been the worst-kept secret that an API exists on every Plex Media Server. We say “worst-kept secret” because many people have spent a lot of time over the years documenting and attempting to keep up with the changes to this interface. Because tinkering and enhancement has always been present around the personal media and home lab spaces, we applaud all of these efforts.
Today, we are here to take your efforts to the next level. For the first time, we are publishing official API documentation for your Plex Media Server!
Before we dig in here, let’s start by answering the question of: why now? The answer is fairly simple. We have never been able to build out all of the requested functionality that people can dream up and drop into the Feature Suggestions section of the forums. There are amazing ideas in there that, for various reasons, we haven’t been able to explore and provide solutions for these ideas and use cases.
Therefore, instead of us saying no to each of these worthy ideas, maybe there is someone out there (is it you?!) who wants to tackle these opportunities. We have so much love for the development community—passionate people who are curious, creative, and who love building things. We want to do everything we can to see the projects and ideas of this community come to life
The release of the PMS API documentation is a starting point for this path that all are welcome to use. If we don’t have the solution that fits your exact use case, then this might be where you can explore finding or creating that solution.
Which brings us to PMS. This is the exciting part. This opens the door for some exciting growth of the server. Why can’t a PMS store and stream out audiobooks? Why can’t we embrace a common schema for different media types and give you more ways to curate and stream more of the media that is important to you?
There are already apps and ideas that leverage this concept to deliver things like an audiobook experience through a Plex Media Server. Think of how incredible these experiences could become with a bit of PMS enhancement, some API documentation, and a community that loves to build amazing things?
Releasing the documentation on the API is a step on the path of helping this community grow. We are also taking the next step in creating a dedicated space in the Plex Forums where we can engage, answer questions, and hopefully highlight some of the awesome creations made using the API.
While the forum stuff is fun, let’s get to why we are all here. So what can you do with the PMS API?
The short answer is: A LOT! You can query all items in a library or set the artwork for an item. Server functions, like how to analyze an item, are defined. Playlists, collections, and activities all have some functions and queries.
Using API queries, you can search, rate, or check for updates. Want to tune a channel on your DVR? Yup. There are tons of GETs, PUTs, POSTS, and more in the API documentation.
The API also includes information on authentication, which is necessary to handle up front, as the API calls don’t work without proper authentication.
As part of this effort, we are excited to announce a significant security enhancement to Plex.tv’s authentication system. We’re introducing JSON Web Token (JWT) authentication that provides better security and shorter token lifespans.
This effort has been in development for a while. The new JWT enhances security through:
- Short-lived tokens: Tokens expire after 7 days
- Modern standards: JWT uses current best practices in web security to keep your data safe.
- Better clock synchronization: Built-in timestamp validation helps devices stay in sync
The new system uses a public-key authentication model where each device uploads a public key (JWK) and then requests short-lived JWT tokens. Here’s the flow:
- Device Key Registration – your device or solution will register its public key with our auth endpoint at plex.tv
- Token Refresh Process – Once registered, your device can refresh its token every 7 days
- Exchange your JWT for a Plex Token – this will return a new JWT valid for 7 days
And once you have a JWT token, you can use it exactly like the old tokens in the X-Plex-Token header!
This also enhances the developer experience through:
- Familiar Interface: Same X-Plex-Token header usage
- Clear Error Codes: Specific error responses for different failure modes
- Rate Limiting: Built-in protection against abuse
Check out the PMS API docs for lots more information, including API examples, more details on the information mentioned here, error handling, technical details, and much more. Still have questions? Feel free to post them in the Dev Community section of the forums!
This would be a great place to end, wouldn’t it? Lots of cool new stuff.
But… you are still here. Ok, how about just a little bit more? What’s better than a sneak peek at what is coming up next for PMS?
We have been hard at work setting the stage for this next act of PMS. And soon this will kick off with our upcoming release of Custom Agents. This is a new and more secure method for ingesting the metadata that you want for the media on your server. This will present a new way to run your own metadata provider – similar to the ones Plex provides today – and ingest them in PMS. It will allow you to have multiple metadata sources side-by-side, prioritize them, and ensure your media gets rendered just the way you like it!
Custom Agents (and the updated API docs for use of Custom Agents) will be launching this year and coming to a PMS near you!
Thanks for taking a few minutes to check out the PMS API with us. The PMS API docs are available today at https://developer.plex.tv, and we hope to see you in the forums at https://forums.plex.tv/c/dev-community/113!
About Kevin
A Plexian for two years and counting, Kevin Wanke works with the engineering teams working on Personal Media and Discover features. Even before joining Plex, Kevin has been an avid user and part of the community for 12+ years. He’s grown his server solutions from a modest Xbox with XBMC to the point of being the de facto IT go-to for many friends and family. Before joining Plex, Kevin led engineering teams in various industries including product development in the cash management and physical security space as well as a large courtroom recording equipment and software provider.
About Marcelo
Marcelo has been a software developer since 2004, working with Ruby for the past 16 years. During his career, he has used a variety of languages to build a diverse range of applications, from betting systems to financial market software. While he has focused primarily on Ruby in recent years, he still enjoys occasional Android development.
When he is not writing code, his passions are video games, movies, and BBQing, though not necessarily in that order. Above all, he loves spending time with his 2-year-old and brewing a great cup of coffee.
More Support
Want a deeper dive? We’ve got you covered:
Dev API Corner
Need to start from the beginning? Here’s how to get your server up and running:
Intro to Plex
Quick-Start Guide to Server Set-Up
More on Plex Media Server Installation
More from Plex Pro Week ‘25
