| Free | Plus | Pro | |
| Roll20 API |
 |
This page is about a feature exclusive to Pro subscribers, or to players in a Game created by a subscriber. If you'd like to use this feature, consider upgrading your account.
The Roll20 API provides a powerful way to customize and enhance your game. You create code scripts that instruct Roll20 during gameplay, like moving a piece, adding status markers to tokens, or rolling dice. Using APIs is simple and straightforward to get started, but the possibilities are endless.
API Guides and Documentation
- API: Script Index (Community Wiki)
- API: Cookbook
- API: Basic Examples
- API: Advanced Examples
- API: Advanced Use Guide
- API: Sandbox Model
- API: Function Documentation
- API: Chat
- API: Objects
- API: Events
- API: Utility Functions
- API: Settings Page Overview
- API: Debugging
- API: Token Markers
Acknowledgments
A special thanks to our Forum Champion (and Arcane Scriptomancer), The Aaron, for his willingness and dedication to sharing his knowledge with the Roll20 Community!
How do I install an API script using the one-click script library?
- Navigate to the game landing page for the desired game.
- Click on the Settings dropdown and select API Scripts.
- In the Script Library dropdown, locate the needed script.
- Click the Add Script button.
- You can now start using the script in your game!
How do I install an API script if I want to write my own code or I want to use code from an external source?
It's a similar process to installing a script using our one-click script library.
- Navigate to the game landing page for the desired game.
- Click on the Settings dropdown and select API Scripts.
- In the API Settings page, click the New Script tab.
- You'll be taken to a code editor window where you can insert your script code and name the script.
- Copy-paste the script code and provide a name for the script.
- Click the Save Script button.
- The API sandbox will restart, and you can now start using the script in-game.
If you obtained the script from an external source, refer to the script's description for important information and instructions.
Help! I can't get my script to work!
If you're looking for general assistance with API troubleshooting, check out our article here. If you are looking for more advanced debugging advice and information, check out our article here. If you're still having issues, feel free to create a post on our API Forum.
If I want to write a script, what do I need to get started?
Scripts for the Roll20 API are written in JavaScript. You only need a basic understanding of the language to get started, but if you want to learn more about JavaScript, this Codecademy course can help teach you.
To get started, your first stop should be the Advanced Use Guide.
How does it work?
You write scripts that listen to events that happen during the game. Scripts can check to make sure that rules are followed, change properties on objects and tokens, and even provide custom chat commands. Your scripts have a game-wide impact, influencing both the GM and all players' actions. Advanced scripts can also run independently, performing automatic actions such as moving a token on a patrol route or nudging players when their turn is taking too long.
Where can I find pre-made scripts?
The API Script community is fairly active with members creating and discussing scripts all the time. There are 3 basic places to look for new scripts:
- The Official Roll20 API Script Repo on GitHub. This is where you'll find the current version of scripts that authors have submitted for inclusion in the repo.
- The Roll20 API Script Forum. This is where scripts tend to show up first and where discussion happens about scripts that are being written or need changes. This is also where you can post and ask for help from the community in creating a script you've thought of or finding a script to fill a need.
- The Wiki's API Script index. This is a good source of information about scripts that are available.
Contributing API Scripts to the Community
If you create a script that you'd like to offer to the rest of the Roll20 community, you can submit it to be included in the Roll20 API Script Repository. Having your script approved by the Roll20 staff and included in the repository will unlock the "API Scripter" forum tag for your account and will allow you to advertise via Patreon or Patreon-like sites (see below for more info). To find out what you need to do to correctly submit your script to the repository go to the Official Roll20 API Script Repo.
Patreon and Tipeee Linking Rules for Community Sheet Contributors
For API script authors that are contributing to the Roll20 API Script Repo, they are approved to advertise via subscription/donation service sites: Patreon and Tippee. Roll20 is not responsible for any payment transactions and cannot enforce any private arrangements.
In order to qualify, an API script author must first have their script contribution approved by the Roll20 staff and included in the Roll20 API Script Repo.
You will want to include your Patreon or Tipeee account information in the sheet.json file that should be included with your script submission on GitHub.
The json file should have one of these fields added to it if you wish to advertise with Patreon or Tipeee:
patreon: Place the URL for a Patreon campaign here, and it will appear under your script's description when selected. (e.g."https://www.patreon.com/<name>")
tipeee: Place the URL for a Tipeee here, and it will appear under your script's description when selected. (e.g. "https://www.tipeee.com/<name>")
For more information, see https://github.com/Roll20/roll20-api-scripts#contributing.Linking to Patreon/Tipeee on the Roll20 Forums
Linking to Patreon or Tipeee on the Roll20 Forums is only permitted for pre-approved community members who have contributed either Character Sheets or API Scripts. If you wish to solicit users directly for funding you may do so privately, but no such links are permitted in a public forum without any contributed material.