The MuckRock API, or application programming interface, provides a way to access MuckRock data programmatically. This guide will give you what you need to get up and running. The API is accessible through HTTPS and our Python library python-muckrock. We recommend our library for scripts, automations and notebooks. It provides a convenient helper for authenticating with your MuckRock account, searching the database and filing records requests.
The MuckRock API has a built-in internal referential schema that lists all parameters for different endpoints and operations. We also encourage users to read through our Python library's getting started section for concrete examples of a workflow.
The API (and generally, the entire site) is rate limited to one request per second, however you can burst these requests up to 20 per second for as long as the average runs less than 1 per second over a 20 second period.
The current API endpoint is https://www.muckrock.com/api_v2/. It is accessible without any authentication. Making a query against this top-level address will provide a list of available objects and their endpoints. The current list of available objects includes:
Some endpoint operations are accessible without providing any authentication. Others, like filing a request, require authentication. If you're ever unsure, if an operation requires authentication and you aren't authenticated you'll receive a response: "Authentication credentials were not provided".
Authentication is done using MuckRock Accounts access tokens. To
retrieve your first access token, you must authenticate using username
and password with a POST to the following endpoint:
https://accounts.muckrock.com/api/token/
Authenticating with this endpoint you will receive a response that
includes an access and refresh token. The access token is valid for 5
minutes after which it will stop working. To continue making API
requests, you will need to POST the refresh token you received earlier
to the following endpoint to be issued an updated access and refresh
token:
https://accounts.muckrock.com/api/refresh/