> ## Documentation Index
> Fetch the complete documentation index at: https://docs.case.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Case Search

> Find cases by topic and discover related authorities

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.

```bash title="Endpoint" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /legal/v1/find
```

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl -X POST https://api.case.dev/legal/v1/find \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "qualified immunity excessive force police",
      "jurisdiction": "us-federal",
      "numResults": 10
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev legal:v1 find \
    --query "qualified immunity excessive force police" \
    --jurisdiction us-federal \
    --num-results 10
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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)}...`);
  }
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  result = client.legal.v1.find(
      query='qualified immunity excessive force police',
      jurisdiction='us-federal',
      num_results=10
  )

  print(f'Found {result.found} candidates')

  for candidate in result.candidates:
      print(f'{candidate.title}')
      print(f'  {candidate.url}')
      print(f'  {candidate.snippet[:100]}...')
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  result, _ := client.Legal.V1.Find(ctx, casedev.LegalV1FindParams{
      Query:        casedev.F("qualified immunity excessive force police"),
      Jurisdiction: casedev.F("us-federal"),
      NumResults:   casedev.F(int64(10)),
  })

  fmt.Printf("Found %d candidates\n", result.Found)

  for _, candidate := range result.Candidates {
      fmt.Println(candidate.Title)
      fmt.Printf("  %s\n", candidate.URL)
      fmt.Printf("  %s...\n", candidate.Snippet[:100])
  }
  ```
</CodeGroup>

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

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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."
}
```

<Warning>
  **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.
</Warning>

***

## Find similar cases

Given a legal document URL, find semantically similar sources. Useful for expanding research or finding citing cases.

```bash title="Endpoint" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /legal/v1/similar
```

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl -X POST https://api.case.dev/legal/v1/similar \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://www.courtlistener.com/opinion/118365/bush-v-gore/",
      "numResults": 10
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev legal:v1 similar \
    --url "https://www.courtlistener.com/opinion/118365/bush-v-gore/" \
    --num-results 10
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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}`);
  }
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  result = client.legal.v1.similar(
      url='https://www.courtlistener.com/opinion/118365/bush-v-gore/',
      num_results=10
  )

  print(f'Found {result.found} similar sources')

  for source in result.similar_sources:
      print(f'{source.title}')
      print(f'  {source.url}')
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  result, _ := client.Legal.V1.Similar(ctx, casedev.LegalV1SimilarParams{
      URL:        casedev.F("https://www.courtlistener.com/opinion/118365/bush-v-gore/"),
      NumResults: casedev.F(int64(10)),
  })

  fmt.Printf("Found %d similar sources\n", result.Found)

  for _, source := range result.SimilarSources {
      fmt.Println(source.Title)
      fmt.Printf("  %s\n", source.URL)
  }
  ```
</CodeGroup>

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

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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.

```bash title="Endpoint" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /legal/v1/research
```

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl -X POST https://api.case.dev/legal/v1/research \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "employment discrimination disparate impact",
      "additionalQueries": [
        "Title VII disparate impact theory",
        "Griggs v Duke Power significance"
      ],
      "numResults": 15
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev legal:v1 research \
    --query "employment discrimination disparate impact" \
    --additional-query "Title VII disparate impact theory" \
    --additional-query "Griggs v Duke Power significance" \
    --additional-query "statistical evidence employment discrimination" \
    --jurisdiction us-federal \
    --num-results 15
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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]}"`);
    }
  }
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  result = client.legal.v1.research(
      query='employment discrimination disparate impact',
      additional_queries=[
          'Title VII disparate impact theory',
          'Griggs v Duke Power significance',
          'statistical evidence employment discrimination'
      ],
      jurisdiction='us-federal',
      num_results=15
  )

  print(f'Deep search found {result.found} sources')

  for candidate in result.candidates:
      print(f'{candidate.title}')

      # Deep search includes highlighted passages
      if candidate.highlights:
          print(f'  Key passage: "{candidate.highlights[0]}"')
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  result, _ := client.Legal.V1.Research(ctx, casedev.LegalV1ResearchParams{
      Query: casedev.F("employment discrimination disparate impact"),
      AdditionalQueries: casedev.F([]string{
          "Title VII disparate impact theory",
          "Griggs v Duke Power significance",
          "statistical evidence employment discrimination",
      }),
      Jurisdiction: casedev.F("us-federal"),
      NumResults:   casedev.F(int64(15)),
  })

  fmt.Printf("Deep search found %d sources\n", result.Found)

  for _, candidate := range result.Candidates {
      fmt.Println(candidate.Title)

      // Deep search includes highlighted passages
      if len(candidate.Highlights) > 0 {
          fmt.Printf("  Key passage: \"%s\"\n", candidate.Highlights[0])
      }
  }
  ```
</CodeGroup>

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

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # 1. Deep search with variations
  curl -X POST https://api.case.dev/legal/v1/research \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "topic",
      "additionalQueries": ["variation 1", "variation 2"],
      "jurisdiction": "us-federal",
      "numResults": 20
    }'

  # 2. Verify top candidates
  curl -X POST https://api.case.dev/legal/v1/verify \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Candidate Title, 457 U.S. 800"
    }'

  # 3. Find similar cases to the best result
  curl -X POST https://api.case.dev/legal/v1/similar \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://www.courtlistener.com/opinion/...",
      "numResults": 5
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # 1. Deep search with variations
  casedev legal:v1 research \
    --query "topic" \
    --additional-query "variation 1" \
    --additional-query "variation 2" \
    --jurisdiction us-federal \
    --num-results 20

  # 2. Verify top candidates
  casedev legal:v1 verify --text "Candidate Title, 457 U.S. 800"

  # 3. Find similar cases to the best result
  casedev legal:v1 similar \
    --url "https://www.courtlistener.com/opinion/..." \
    --num-results 5
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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: [] };
  }
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  def research_topic(topic: str, jurisdiction: str = None):
      # 1. Deep search with variations
      research = client.legal.v1.research(
          query=topic,
          additional_queries=generate_variations(topic),
          jurisdiction=jurisdiction,
          num_results=20,
      )

      # 2. Verify top candidates
      verified = []
      for candidate in research.candidates[:10]:
          result = client.legal.v1.verify(text=candidate.title)
          if result.summary.verified > 0:
              verified.append({
                  **candidate,
                  "verification": result.citations[0],
              })

      # 3. Find similar cases to the best result
      if verified:
          similar = client.legal.v1.similar(
              url=verified[0]["url"],
              num_results=5,
          )
          return {"primary": verified, "related": similar.similar_sources}

      return {"primary": verified, "related": []}
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  // 1. Deep search with variations
  research, _ := client.Legal.V1.Research(ctx, casedev.LegalV1ResearchParams{
      Query:            casedev.F(topic),
      AdditionalQueries: casedev.F(generateVariations(topic)),
      Jurisdiction:     casedev.F(jurisdiction),
      NumResults:       casedev.F(int64(20)),
  })

  // 2. Verify top candidates
  var verified []Candidate
  for _, candidate := range research.Candidates[:10] {
      result, _ := client.Legal.V1.Verify(ctx, casedev.LegalV1VerifyParams{
          Text: casedev.F(candidate.Title),
      })
      if result.Summary.Verified > 0 {
          verified = append(verified, candidate)
      }
  }

  // 3. Find similar cases to the best result
  if len(verified) > 0 {
      similar, _ := client.Legal.V1.Similar(ctx, casedev.LegalV1SimilarParams{
          URL:        casedev.F(verified[0].URL),
          NumResults: casedev.F(int64(5)),
      })
      // Use similar.SimilarSources as related cases
  }
  ```
</CodeGroup>

### Build a case timeline

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # Find the seed case
  curl -X POST https://api.case.dev/legal/v1/find \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "seed case topic",
      "numResults": 1
    }'

  # Find similar cases across time
  curl -X POST https://api.case.dev/legal/v1/similar \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://www.courtlistener.com/opinion/...",
      "numResults": 25
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # Find the seed case
  casedev legal:v1 find --query "seed case topic" --num-results 1

  # Find similar cases across time (use the URL from above)
  casedev legal:v1 similar \
    --url "https://www.courtlistener.com/opinion/..." \
    --num-results 25
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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));
  }
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  def build_timeline(seed_case: str):
      # Find the seed case
      search = client.legal.v1.find(query=seed_case, num_results=1)
      seed_url = search.candidates[0].url

      # Find similar cases across time
      similar = client.legal.v1.similar(url=seed_url, num_results=25)

      # Sort by date
      sources = [s for s in similar.similar_sources if s.published_date]
      sources.sort(key=lambda s: s.published_date)
      return sources
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  // Find the seed case
  search, _ := client.Legal.V1.Find(ctx, casedev.LegalV1FindParams{
      Query:      casedev.F(seedCase),
      NumResults: casedev.F(int64(1)),
  })
  seedURL := search.Candidates[0].URL

  // Find similar cases across time
  similar, _ := client.Legal.V1.Similar(ctx, casedev.LegalV1SimilarParams{
      URL:        casedev.F(seedURL),
      NumResults: casedev.F(int64(25)),
  })

  // Sort similar.SimilarSources by PublishedDate
  sort.Slice(similar.SimilarSources, func(i, j int) bool {
      return similar.SimilarSources[i].PublishedDate < similar.SimilarSources[j].PublishedDate
  })
  ```
</CodeGroup>

### Jurisdiction-specific research

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl -X POST https://api.case.dev/legal/v1/find \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "your query",
      "jurisdiction": "us-federal",
      "numResults": 5
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # Research across multiple jurisdictions
  casedev legal:v1 find --query "your query" --jurisdiction us-federal --num-results 5
  casedev legal:v1 find --query "your query" --jurisdiction california --num-results 5
  casedev legal:v1 find --query "your query" --jurisdiction new-york --num-results 5
  casedev legal:v1 find --query "your query" --jurisdiction texas --num-results 5
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  // 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
    }));
  }
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # Research across multiple jurisdictions
  def multi_jurisdiction_search(query: str):
      jurisdictions = ['us-federal', 'california', 'new-york', 'texas']

      results = []
      for j in jurisdictions:
          result = client.legal.v1.find(
              query=query, jurisdiction=j, num_results=5
          )
          results.append({"jurisdiction": j, "cases": result.candidates})

      return results
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  // Research across multiple jurisdictions
  jurisdictions := []string{"us-federal", "california", "new-york", "texas"}

  for _, j := range jurisdictions {
      result, _ := client.Legal.V1.Find(ctx, casedev.LegalV1FindParams{
          Query:        casedev.F(query),
          Jurisdiction: casedev.F(j),
          NumResults:   casedev.F(int64(5)),
      })
      fmt.Printf("%s: %d cases\n", j, result.Found)
  }
  ```
</CodeGroup>

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