<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>

All APIs besides the authentication endpoints are served from https://api.www.documentcloud.org/api.

<aside> <img src="/icons/command-line_gray.svg" alt="/icons/command-line_gray.svg" width="40px" />

If you develop in Python, check out our python-documentcloud package and its corresponding documentation to easily access the DocumentCloud API.

</aside>

Overview

The API end points are generally organized as /api/<resource>/ representing the entirety of the resource, and /api/<resource>/<id>/ representing a single resource identified by its ID. All REST actions are not available on every endpoint, and some resources may have additional endpoints, but the following are how HTTP verbs generally map to REST operations:

/api/<resource>/

HTTP Verb REST Operation Parameters
GET List the resources May support parameters for filtering
POST Create a new resource Must supply all required fields, and may supply all non-read only fields

/api/<resource>/<id>/

HTTP Verb REST Operation Parameters
GET Display the resource
PUT Update the resource Same as for creating - all required fields must be present. For updating resources PATCH is usually preferred, as it allows you to only update the fields needed. PUT support is included for completeness
PATCH Partially update the resource Same as for creating, but all fields are optional
DELETE Destroy the resources

A select few of the resources support some bulk operations on the /api/<resource>/ route:

HTTP Verb REST Operation Parameters
POST Bulk create A list of objects, where each object is what you would POST for a single object
PUT Bulk update A list of objects, where each object is what you would PUT for a single object — except it must also include the ID
PATCH Bulk partial update A list of objects, where each object is what you would PATCH for a single object — except it must also include the ID
DELETE Bulk destroy Bulk destroys will have a filtering parameter, often required, to specify which resources to delete

Responses

Lists response will be of the form

{
    "next": <next url if applicable>,
    "previous": <previous url if applicable>,
    "results": <list of results>
}

with a 200 status code. The document search route will also include a count key, with a total count of all documents returned by the search.

Getting a single resource, creating and updating will return just the object. Create uses a 201 status code and get and update will return 200.

Delete will have an empty response with a 204 status code.

Batch updates will contain a list of objects updated with a 200 status code.

Specifying invalid parameters will generally return a 400 error code with a JSON object with a single "error" key, whose value will be an error message. Specifying an ID that does not exist or that you do not have access to view will return status 404. Trying to create or update a resource you do not have permission to will return status 403.

Pagination