Search for legal sources by topic, find similar cases, and conduct deep research with multiple query variations.
Find cases
Search for legal sources including cases, statutes, and regulations from authoritative databases.
const result = await client.legal.find({
query: 'qualified immunity excessive force police',
jurisdiction: 'us-federal',
numResults: 10
});
console.log(`Found ${result.found} candidates`);
for (const candidate of result.candidates) {
console.log(`${candidate.title}`);
console.log(` ${candidate.url}`);
console.log(` ${candidate.snippet.slice(0, 100)}...`);
}
Parameters
| Parameter | Type | Description |
|---|
query | string | Search query (3-1,000 characters) |
jurisdiction | string | Optional jurisdiction ID (e.g., us-federal, california) |
numResults | number | Results to return (1-25, default 10) |
Response
{
"query": "qualified immunity excessive force police",
"jurisdiction": "us-federal",
"found": 10,
"candidates": [
{
"url": "https://www.courtlistener.com/opinion/...",
"title": "Harlow v. Fitzgerald, 457 U.S. 800 (1982)",
"snippet": "Government officials performing discretionary functions are shielded from liability...",
"source": "courtlistener.com",
"publishedDate": "1982-06-24"
}
],
"hint": "IMPORTANT: Use legal.verify() on each candidate before citing."
}
Always verify before citing. Search results are candidates, not verified sources. Use legal.verify() to confirm each citation exists in the database before your user cites it.
Find similar cases
Given a legal document URL, find semantically similar sources. Useful for expanding research or finding citing cases.
const result = await client.legal.similar({
url: 'https://www.courtlistener.com/opinion/118365/bush-v-gore/',
numResults: 10
});
console.log(`Found ${result.found} similar sources`);
for (const source of result.similarSources) {
console.log(`${source.title}`);
console.log(` ${source.url}`);
}
Parameters
| Parameter | Type | Description |
|---|
url | string | URL of the source document |
jurisdiction | string | Optional jurisdiction filter |
numResults | number | Results to return (1-25, default 10) |
startPublishedDate | string | Only include sources after this date (ISO format) |
Response
{
"sourceUrl": "https://www.courtlistener.com/opinion/118365/bush-v-gore/",
"jurisdiction": "all",
"found": 10,
"similarSources": [
{
"url": "https://www.courtlistener.com/opinion/...",
"title": "Reynolds v. Sims, 377 U.S. 533 (1964)",
"snippet": "The Equal Protection Clause requires substantially equal legislative representation...",
"source": "courtlistener.com",
"publishedDate": "1964-06-15"
}
]
}
Deep research
Conduct comprehensive research with multiple query variations. Uses advanced search to find sources across different phrasings of the legal issue.
const result = await client.legal.research({
query: 'employment discrimination disparate impact',
additionalQueries: [
'Title VII disparate impact theory',
'Griggs v Duke Power significance',
'statistical evidence employment discrimination'
],
jurisdiction: 'us-federal',
numResults: 15
});
console.log(`Deep search found ${result.found} sources`);
for (const candidate of result.candidates) {
console.log(`${candidate.title}`);
// Deep search includes highlighted passages
if (candidate.highlights?.length > 0) {
console.log(` Key passage: "${candidate.highlights[0]}"`);
}
}
Parameters
| Parameter | Type | Description |
|---|
query | string | Primary search query |
additionalQueries | string[] | Up to 5 alternative phrasings |
jurisdiction | string | Optional jurisdiction filter |
numResults | number | Results to return (1-25, default 10) |
Response
{
"query": "employment discrimination disparate impact",
"additionalQueries": ["Title VII disparate impact theory", "..."],
"jurisdiction": "us-federal",
"searchType": "deep",
"found": 15,
"candidates": [
{
"url": "https://www.courtlistener.com/opinion/...",
"title": "Griggs v. Duke Power Co., 401 U.S. 424 (1971)",
"snippet": "The Act proscribes not only overt discrimination but also practices...",
"highlights": [
"Congress directed the thrust of the Act to the consequences of employment practices",
"The touchstone is business necessity"
],
"source": "courtlistener.com",
"publishedDate": "1971-03-08"
}
]
}
When to use deep research
| Scenario | Use |
|---|
| Quick case lookup | legal.find() |
| Thorough brief research | legal.research() with query variations |
| Finding all related cases | legal.similar() from a key case |
Common patterns
Research workflow
async function researchTopic(topic: string, jurisdiction?: string) {
// 1. Deep search with variations
const research = await client.legal.research({
query: topic,
additionalQueries: generateVariations(topic),
jurisdiction,
numResults: 20
});
// 2. Verify top candidates
const verified = [];
for (const candidate of research.candidates.slice(0, 10)) {
const result = await client.legal.verify({ text: candidate.title });
if (result.summary.verified > 0) {
verified.push({
...candidate,
verification: result.citations[0]
});
}
}
// 3. Find similar cases to the best result
if (verified.length > 0) {
const similar = await client.legal.similar({
url: verified[0].url,
numResults: 5
});
return { primary: verified, related: similar.similarSources };
}
return { primary: verified, related: [] };
}
Build a case timeline
async function buildTimeline(seedCase: string) {
// Find the seed case
const search = await client.legal.find({ query: seedCase, numResults: 1 });
const seedUrl = search.candidates[0].url;
// Find similar cases across time
const similar = await client.legal.similar({
url: seedUrl,
numResults: 25
});
// Sort by date
return similar.similarSources
.filter(s => s.publishedDate)
.sort((a, b) => new Date(a.publishedDate) - new Date(b.publishedDate));
}
Jurisdiction-specific research
// Research across multiple jurisdictions
async function multiJurisdictionSearch(query: string) {
const jurisdictions = ['us-federal', 'california', 'new-york', 'texas'];
const results = await Promise.all(
jurisdictions.map(j =>
client.legal.find({ query, jurisdiction: j, numResults: 5 })
)
);
return jurisdictions.map((j, i) => ({
jurisdiction: j,
cases: results[i].candidates
}));
}
Supported sources
Search covers authoritative legal databases:
| Source | Content |
|---|
| CourtListener | ~10M court opinions |
| Cornell Law | Statutes, regulations, legal encyclopedias |
| Supreme Court | All SCOTUS opinions |
| govinfo.gov | Federal Register, CFR, USC |
| State courts | Via regional reporters |
