<aside> <img src="/icons/book-closed_blue.svg" alt="/icons/book-closed_blue.svg" width="40px" /> MuckRock’s User Guide gives you everything to make the most out of MuckRock’s suite of tools. If this has helped you, consider donating to support our work!

</aside>

Add-Ons make it easy for anyone to add and share additional features within the DocumentCloud platform, ranging from automating repetitive tasks to integrating machine learning and data visualization techniques.

Overview

For end users, using an Add-On is as simple as selecting documents or executing a search, picking which feature they’d like to apply to the results, and then submitting.

On the backend, Add-Ons execute Python scripts organized in a standard way, hosted and processed right on GitHub.

Add-Ons can take advantage of the full DocumentCloud API as well as the ability to call other third-party services and a few Add-On specific functions such as the ability to store arbitrary files, send a user emails, and track the progress of an Add-Ons' execution and display messages to the user.

In addition to being able to execute Add-Ons via the DocumentCloud user interface, these extensions are also designed to run smoothly on your local computer — simply clone the repository to your local device, install the DocumentCloud Python wrapper, and then invoke the main.py file of the Add-On. Invocation requires your DocumentCloud username and password if the add-on requires authentication, which is used to fetch a refresh and access token. They can be passed in as command line arguments (--username and --password), or as environment variables (DC_USERNAME and DC_PASSWORD).

You can also pass in a list of document IDs (--documents), a search query (--query), and JSON parameters for your Add-On (--data) - be sure to properly quote your JSON at the command line.

Example invocation:

python main.py --documents 123 --data '{"name": "World"}'

We have an Add-On template hosted on GitHub that demonstrates basic features, as well as a variety of other example Add-Ons that might serve as a useful base for your own work.

DocumentCloud Premium and AI Credits

Some Add-Ons require AI credits to run as they use paid services to perform operations like OCR, document translation or the Add-On uses AI tools which have costs.

DocumentCloud Premium comes with AI credits for both professional and organizational accounts on MuckRock. You can upgrade your account or organization on the MuckRock Select Plan page. You can also upgrade your plan by clicking on the drop-down menu named "Premium" once you log in. It will link you to the same upgrade plan page.

To check your AI credit balance, you can:

1. Click on the name of your organization in the top navigation bar and your monthly allowance will appear there. If you are a freelancer, you click on the second drop-down menu (next to your account name) and your balance should appear there as well.
2. Click on a premium Add-On from the Add-On run menu. Your allowance will appear in the run menu.
3. When uploading a document, your AI credit balance also appears as text in the upload menu where you can select which OCR engine you want to use.

AI Credit usage is logged. If you want to know how your AI credits were used, contact us.

At this time, there are eight premium Add-Ons: