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