REST API, v4.4
APIs for developers and researchers that need granular legal data.
After more than a decade of development, these APIs are powerful. Our case law API was the first. Our PACER and oral argument APIs are the biggest. Our webhooks push data to you. Our citation lookup tool can fight hallucinations in AI tools.
Let's get started. To see and browse all the API URLs, click the button below:
We could have also pulled up that same information using curl, with a command like:
curl "https://www.courtlistener.com/api/rest/v4/"
Note that when you press the button in your browser, you get an HTML result, but when you run curl you get a JSON object. This is discussed in more depth below.
Warning
Something unusual just happened. You didn't authenticate to the API. To encourage experimentation, many of our APIs are open by default. The biggest gotcha people have is that they forget to enable authentication before deploying their code. Don't make this mistake! Remember to add authentication.
The APIs listed in this response can be used to make queries against our database or search engine.
To learn more about an API, you can send an HTTP OPTIONS request, like so:
curl -X OPTIONS "https://www.courtlistener.com/api/rest/v4/"
Sending an OPTIONS request to an API endpoint is one of the best ways to understand the API.
Support
Questions about the APIs should be submitted to our GitHub Discussions forum or via our contact form. We prefer that questions be posted in the forum so they can help others.
Ask in GitHub Discussions Send us a Private Message
Tweaks or suggestions to this documentation can be made via the Feedback button at the top of any page.
Data Models
It can be helpful to understand the underlying database schema behind our API.
API Overview
This section explains the general principles of the API. These principals are driven by the features supported by the Django REST Framework. To go deep on any of these sections, we encourage you to check out the documentation there.
Permissions
Some of our APIs are only available to select users. If you need greater access to these APIs, please get in touch.
All other endpoints are available according to the throttling and authentication limitations listed below.
Your Authorization Token
Your authentication token is available on your CourtListener profile.
Authentication
Authentication is necessary to monitor and control the system, and helps us assist with any errors that may occur.
There are currently three types of authentication available on the API:
All of these methods are secure, so the choice of which to use is generally a question of convenience. Our recommendations are:
- Use Token Authentication for programmatic API access.
- Use Cookie/Session Authentication if you already have a user's cookie or are developing a system where you can ask the user to log into CourtListener.
- Use Basic Authentication if that's all your client supports.
Token Authentication
To use token authentication, use the Authorization HTTP Header with the word Token, a space, and then your key:
Authorization: Token <your-token-here>
Using curl, this looks like:
curl "https://www.courtlistener.com/api/rest/v4/clusters/" \
--header 'Authorization: Token <your-token-here>'
Note that quotes are used to enclose the whitespace in the header.
Warning
A common mistake is to forget the word "Token" in the header.
Cookie Authentication
To use Cookie Authentication log into Courtlistener and pass the cookie value using the standard cookie headers.
HTTP Basic Authentication
To use HTTP Basic Authentication using curl, you might do something like this:
curl --user "harvey:your-password" \
"https://www.courtlistener.com/api/rest/v4/clusters/"
You can also do it in your browser with a url like:
https://harvey:your-password@www.courtlistener.com/api/rest/v4/clusters/
But if you're using your browser, you might as well just log in.
Serialization Formats
Requests may be serialized as HTML, JSON, or XML. JSON is the default if no format is specified. The format you wish to receive is requested via the HTTP Accept header.
The following media types and parameters can be used:
- HTML: The media type for HTML is
text/html. - JSON: The media type for JSON is
application/json. Providing theindentmedia type parameter allows clients to set the indenting for the response, for example:Accept: application/json; indent=2. - XML: The media type for XML is
application/xml.
By default, browsers send an Accept header similar to:
text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
This states that text/html is the preferred serialization format. The API respects that, returning HTML when requested by a browser and returning JSON when no Accept header is provided, because JSON is the default.
If you wish to set the Accept header using a tool like curl, you can do so using the --header flag:
curl --header "Accept: application/xml" \
"https://www.courtlistener.com/api/rest/v4/clusters/"
All data is serialized using the utf-8 charset.
Parsing Uploaded Content
If you are a user that has write access to these APIs (most users do not), you will need to use the Content-Type HTTP header to explicitly set the format of the content you are uploading. The header can be set to any of the values that are available for serialization or to application/x-www-form-urlencoded or multipart/form-data, if you are sending form data.
Query Refinement
Filtering, ordering, counting, pagination, and field selection are discussed on our page about query refinement.
Rate Limits
Our APIs allow 5,000 queries per hour to authenticated users. Creating more than one account per project, person, or organization is forbidden. If you are in doubt, please contact us before creating multiple accounts.
To debug throttling issues:
- Try browsing the API while logged into Courtlistener. If this works and your code fails, it usually means that your token authentication is not configured properly, and your code is getting throttled as an anonymous user, not according to your token.
- Review your recent API usage by looking in your profile, but remember that it will show stats for the browsable API as well.
- Review the authentication/throttling tips in our forum.
If, after checking the above, you need your rate limit increased, please get in touch so we can help.
Performance Tips
A few things to consider that may increase your performance:
Use field selection to limit the serialized payload and defer unused fields, reducing both payload size and database load, especially for large fields.
Avoid doing queries like
court__id=xyzwhen you can instead docourt=xyz. Doing queries with the extra__idintroduces a join that can be expensive.When using the
searchendpoint, smaller result sets are faster. It isn't always possible to tweak your query to return fewer results, but sometimes it is possible to do a more precise query first, thus making a broader query unnecessary. For example, a search for an individual in their expected jurisdiction will be faster than doing it in the entire corpus. This will benefit from profiling in your use case and application.
Special Field Definitions
Placing an HTTP OPTIONS request on an API is the best way to learn about its fields, but some fields require further explanation. Click below to learn about these fields.
APIs
Case Law APIs
We started collecting case law in 2009 and launched this API in 2013 as the first API for legal decisions.
Use this API to build your own collection of case law, complete complex legal research, and more.
PACER Data APIs
We have almost half a billion PACER-related items in the RECAP Archive including dockets, entries, documents, parties, and attorneys. Use these APIs to access and understand this data.
RECAP APIs
Use these APIs to gather data from PACER and to share your PACER data with the public.
Pray and Pay API
Request PACER documents that are not yet available in the RECAP Archive and learn when items become available.
Search API
CourtListener allows you to search across hundreds of millions of items with advanced fields and operators. Use this API to automate the CourtListener search engine.
Judge APIs
Use these APIs to query and analyze thousands of federal and state court judges, including their biographical information, political affiliations, education and employment histories, and more.
Financial Disclosure APIs
All federal judges and many state judges must file financial disclosure documents to indicate any real or perceived biases they may have.
Use these APIs to work with this information.
Oral Argument APIs
CourtListener is home to the largest collection of oral argument recordings on the Internet. Use these APIs to gather and analyze our collection.
Citation Lookup and Verification API
This API can look up either an individual citation or can parse and look up every citation in a block of text. This can be useful as a guardrail to help prevent hallucinated citations.
Citation Graph APIs
Use these APIs to traverse and analyze our network of citations between legal decisions.
Alert APIs
CourtListener is a scalable system for sending alerts by email or webhook based on search queries or cases you wish to follow. Use these APIs to create, modify, list, and delete alerts.
Tag APIs
Use these APIs to create, organize, and manage tags on dockets. Tags help you organize and share collections of cases.
Visualization APIs
To see and make Supreme Court case visualizations, use these APIs.
Available Jurisdictions
We currently have 3,358 jurisdictions that can be accessed with our APIs. Details about the jurisdictions that are available, including all abbreviations, can be found here.
Upgrades and Fixes
Like the rest of the CourtListener platform, this API and its documentation are open source. If this API lacks functionality that you need, please file an issue or a pull request with the functionality.
To update this documentation, use the Feedback link at the top of any page, which allows you to suggest tweaks or send notes.
Getting this kind support is one of the most rewarding things possible for an organization like ours and is a major goal of Free Law Project. Many of the features you use on CourtListener were built by volunteers. We're building something together.
Maintenance Schedule
There is a weekly maintenance window from 21:00-23:59PT on Thursday nights. If you are scheduling cron jobs or otherwise crawling the API, you may experience downtime during this window.
Additionally, we regularly perform bulk tasks on our servers and maintain a public calendar for tracking them. You may encounter larger delays while bulk processing jobs are running.
API Change Log
mike