The MuckRock API

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.

Examples

We provide a public GitHub repository of example code that uses the API. This is a collection of simple python scripts that should give an idea of what kind of things are possible. Since it’s public, feel free to fork the repository and make a pull request with your own examples!

For more examples, check out the projects that resulted from the BuzzFeed FOIA hackathon.

Endpoints

The current API endpoint is https://www.muckrock.com/api_v1/. 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:

  • jurisdiction
  • agency
  • foia
  • communication
  • question
  • statistics
  • user
  • news

Authentication

Most endpoints are accessible without providing any authentication. To access protected data, like your embargoed requests, you’ll need to request a token. Your token can be obtained by making a POST request to /token-auth/ and providing your MuckRock username and password.

response = requests.post(
  'https://www.muckrock.com/api_v1/token-auth/',
  data={
    'username': USERNAME,
    'password': PASSWORD
  }
)
token = response.json()['token']

When making a request, the token should be included as an authentication header.

headers = {'Authorization': 'Token %s' % token}

We provide a convenience method for getting and storing your token.

Pagination

Our responses are paginated, with a default of 50 items per page. The number of results per page can be changed by providing a page_size query argument.

Response Formats

By default, requests to endpoints will return an HTML “explorer” view that is very easy to use in a browser, but not-so-much in code. To get JSON-formatted responses, either include the application/json value to the content-type header or include the format=json query argument.

Submitting Requests

FOIA Requests can be filed through our API! This can be done by sending an authenticated POST request to the /foia/ endpoint. Four values are required when filing:

  1. title (String)
  2. document_request (String)
  3. jurisdiction (Int)
  4. agency (Int)

The title and document_request strings provide the subject and body of the request, respectively. The jurisdiction and agency ints refer to the IDs of jurisdiction and agency objects. Note that the agency should belong to the jurisdiction. If it doesn’t, then an error will be raised. Filing a request without the required data, or with an agency that doesn’t belong to the jurisdiction, will return a HTTP 400 error.

Filing a request through the API will subtract from your account’s available FOIA request count. If no requests have been purchased, the request will be saved as a draft but not sent. After purchasing more requests from your account page, the draft request can be filed manually. Filing a request without any purchased requests will return a HTTP 402 error.

Questions

Reach out to us on Twitter or by email.