## Features
- ⚖️ **Case Law** - Access millions of legal opinions from federal and state courts
- 👨⚖️ **Judge Data** - Comprehensive judge profiles and biographical information
- 🎙️ **Oral Arguments** - Audio recordings with metadata
- 📚 **Citation Tools** - Advanced citation lookup and normalization
- 💼 **PACER Integration** - Federal court docket access
- 🔔 **Real-time Alerts** - Track changes to cases and dockets
- 🤖 **MCP Server** - AI-ready server for integration with Claude and other AI assistants
- 🔍 **Advanced Search** - Powerful search with Elasticsearch backend
- ✨ **Type-safe** - Full TypeScript support with auto-completion
## Installation
```bash
# npm
npm install @us-legal-tools/courtlistener-sdk
# yarn
yarn add @us-legal-tools/courtlistener-sdk
# pnpm
pnpm add @us-legal-tools/courtlistener-sdk
# bun
bun add @us-legal-tools/courtlistener-sdk
```
## Authentication
The CourtListener API requires authentication for most endpoints. Get your API token from [CourtListener](https://www.courtlistener.com/help/api/rest/#authentication).
```typescript
// Set via environment variable
process.env.COURTLISTENER_API_TOKEN = 'your-token';
// Or configure the axios instance directly
import { axiosInstance } from '@us-legal-tools/courtlistener-sdk';
axiosInstance.defaults.headers.common['Authorization'] = 'Token your-token';
```
## Quick Start
### Basic Search
```typescript
import { getSearch } from '@us-legal-tools/courtlistener-sdk';
// Search for Supreme Court cases
const results = await getSearch({
type: 'o', // 'o' for opinions
q: 'miranda rights',
court: 'scotus',
order_by: 'score desc'
});
console.log(`Found ${results.count} cases`);
results.results.forEach(result => {
console.log(`- ${result.caseName} (${result.dateFiled})`);
});
```
### Get Case Details
```typescript
import { getOpinionsId } from '@us-legal-tools/courtlistener-sdk';
// Get a specific opinion
const opinion = await getOpinionsId({ id: 123456 });
console.log(`Case: ${opinion.case_name}`);
console.log(`Court: ${opinion.court}`);
console.log(`Date: ${opinion.date_filed}`);
console.log(`Text: ${opinion.plain_text || opinion.html}`);
```
### Search Judges
```typescript
import { getSearch } from '@us-legal-tools/courtlistener-sdk';
// Search for judges
const judges = await getSearch({
type: 'p', // 'p' for people/judges
q: 'Ruth Bader Ginsburg',
order_by: 'name_reverse asc'
});
judges.results.forEach(judge => {
console.log(`${judge.name_full} - ${judge.court}`);
});
```
### Get Audio Recordings
```typescript
import { getAudio } from '@us-legal-tools/courtlistener-sdk';
// Get oral arguments
const audio = await getAudio({
docket__court: 'scotus',
argued_after: '2023-01-01'
});
audio.results.forEach(recording => {
console.log(`${recording.case_name} - ${recording.date_argued}`);
console.log(`Audio: ${recording.download_url}`);
});
```
## API Reference
### Search Endpoints
- `getSearch` - Universal search endpoint for all content types
- `getSearchV4OpinionsClusters` - Search opinion clusters
- `getSearchV4People` - Search judges and people
- `getSearchV4OralArguments` - Search oral arguments
### Opinion Endpoints
- `getOpinions` - List opinions
- `getOpinionsId` - Get specific opinion
- `getClusters` - List opinion clusters
- `getClustersId` - Get specific cluster
### Judge/Person Endpoints
- `getPeople` - List judges and people
- `getPeopleId` - Get specific person details
- `getPersonDisclosures` - Get financial disclosures
### Docket Endpoints
- `getDockets` - List dockets
- `getDocketsId` - Get specific docket
- `getDocketEntries` - List docket entries
- `getDocketAlerts` - Manage docket alerts
### Audio Endpoints
- `getAudio` - List audio recordings
- `getAudioId` - Get specific audio recording
### Citation Endpoints
- `getCitations` - Citation lookup
- `getCitationNormalize` - Normalize citations
## MCP Server
The MCP server allows AI assistants to interact with the CourtListener API.
### Running the Server
```bash
# Using the SDK directly (requires COURTLISTENER_API_TOKEN env var)
COURTLISTENER_API_TOKEN=your-token npx @us-legal-tools/courtlistener-sdk/mcp
# Or if installed locally
cd node_modules/@us-legal-tools/courtlistener-sdk
COURTLISTENER_API_TOKEN=your-token npm run mcp:server
```
### Integration with Claude
Add to your Claude configuration:
```json
{
"mcpServers": {
"courtlistener": {
"command": "npx",
"args": ["@us-legal-tools/courtlistener-sdk/mcp"],
"env": {
"COURTLISTENER_API_TOKEN": "your-token"
}
}
}
}
```
## Search Types
Use the following types with the search endpoint:
- `o` - Opinions
- `r` - RECAP Archive
- `d` - Dockets
- `p` - People/Judges
- `oa` - Oral Arguments
- `opinion-cluster` - Opinion Clusters
## Advanced Search
```typescript
import { getSearch } from '@us-legal-tools/courtlistener-sdk';
// Complex search with filters
const results = await getSearch({
type: 'o',
q: 'first amendment',
court: 'ca9 ca10 cafc', // Multiple courts
filed_after: '2020-01-01',
filed_before: '2023-12-31',
cited_gt: 50, // Cited more than 50 times
order_by: 'dateFiled desc',
highlight: true
});
```
## Error Handling
```typescript
import { getOpinionsId } from '@us-legal-tools/courtlistener-sdk';
try {
const opinion = await getOpinionsId({ id: 123456 });
} catch (error) {
if (error.response?.status === 401) {
console.error('Invalid API token');
} else if (error.response?.status === 404) {
console.error('Opinion not found');
} else if (error.response?.status === 429) {
console.error('Rate limit exceeded');
} else {
console.error('API error:', error.message);
}
}
```
## Rate Limiting
CourtListener has rate limits based on your account type. Free accounts are limited to 5,000 requests per day.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
## Links
- [npm Package](https://www.npmjs.com/package/@us-legal-tools/courtlistener-sdk)
- [GitHub Repository](https://github.com/beshkenadze/us-legal-tools)
- [CourtListener Website](https://www.courtlistener.com/)
- [CourtListener API Documentation](https://www.courtlistener.com/help/api/)
- [Report Issues](https://github.com/beshkenadze/us-legal-tools/issues/new?labels=bug&template=bug-report.md)
- [Request Features](https://github.com/beshkenadze/us-legal-tools/issues/new?labels=enhancement&template=feature-request.md)
## Support
Need help? Check out our [documentation](https://github.com/beshkenadze/us-legal-tools) or [create an issue](https://github.com/beshkenadze/us-legal-tools/issues/new/choose).
(back to top)
