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. The following parameters are available

agency (Int or List of Ints) *Required
Sets the agency for the request, based on the primary key of they agency. You can obtain the agencies key from the agency API. If you supply a list of ints, one request will be created for each agency.
embargo (Bool)
Will embargo this request as private until 30 days after a response is received. You must have a pro or org account to use this feature.
permanent_embargo (Bool)
Will permanently embargo the request. This option implicitly sets embargo. You must have an org account to use this feature.
title (String) *Required
The title of the request
document_request (String)
The documents you are requesting. This will be inserted into the default form language for a request. Either this or full_text must be specified
full_text (String)
The full text of your request. This fully overrides the default text. Either this or document_request must be specified
attachments (List of strings)
A list of publically available URLs for documents to attach to the request. This is limited to 3 attachments. Documents must be a PDF, image, Word Document, HTML or text document.

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.