### Install Vaquill MCP Server

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Installs the Vaquill Model Context Protocol (MCP) server using pip or runs it directly with uvx. This enables integration with AI tools like Claude Desktop, Cursor, and VS Code.

```bash
pip install vaquill-mcp
```

```bash
uvx vaquill-mcp
```

--------------------------------

### Search API Request Examples

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/authentication.mdx

Demonstrates how to make a search request to the Vaquill API using different programming languages and tools. These examples show the necessary headers and request body structure for a successful search query.

```bash
curl -X POST https://api.vaquill.ai/api/v1/research/search \
  -H "Authorization: Bearer vq_key_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "right to privacy fundamental rights"}'
```

```python
import requests

response = requests.post(
    "https://api.vaquill.ai/api/v1/research/search",
    headers={
        "Authorization": "Bearer vq_key_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={"query": "right to privacy fundamental rights"}
)
```

```javascript
const response = await fetch("https://api.vaquill.ai/api/v1/research/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer vq_key_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ query: "right to privacy fundamental rights" })
});
```

```go
req, _ := http.NewRequest("POST", "https://api.vaquill.ai/api/v1/research/search", body)
req.Header.Set("Authorization", "Bearer vq_key_your_api_key_here")
req.Header.Set("Content-Type", "application/json")
```

--------------------------------

### MCP Integration Setup

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Instructions and configuration details for integrating Vaquill with AI tools like Claude Desktop, Cursor, and VS Code using the Model Context Protocol (MCP).

```APIDOC
## MCP Integration

Connect Vaquill to Claude Desktop, Cursor, VS Code, and other AI tools via the Model Context Protocol. Install the MCP server and configure your client to enable AI assistants to search cases, resolve citations, and traverse citation networks directly.

### Installation

```bash
# Install via pip
pip install vaquill-mcp

# Or run directly with uvx (requires uv)
uvx vaquill-mcp
```

### Configuration

Add the following to your MCP config file (e.g., `claude_desktop_config.json`, `.vscode/mcp.json`):

```json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_api_key_here"
      }
    }
  }
}
```

### Environment Variables

Set the following environment variables for the MCP server:

- **VAQUILL_API_KEY** (Required): Your Vaquill API key.
- **VAQUILL_BASE_URL** (Optional): The base URL for the Vaquill API. Defaults to `https://api.vaquill.ai`.
- **VAQUILL_TIMEOUT** (Optional): Timeout in seconds for API requests. Defaults to `120`.

```bash
export VAQUILL_API_KEY="vq_key_..."
export VAQUILL_BASE_URL="https://api.vaquill.ai"
export VAQUILL_TIMEOUT="120"
```

### Development Setup

To run from source for development:

```bash
git clone https://github.com/Vaquill-AI/vaquill-mcp.git
cd vaquill-mcp
uv sync --all-extras
VAQUILL_API_KEY=vq_key_... uv run vaquill-mcp
```

### MCP Tools Available

| Tool                    | Description                                       |
|-------------------------|---------------------------------------------------|
| `ask_legal_question`    | Legal Q&A grounded in court judgments             |
| `search_legal_cases`    | Boolean keyword search with filters               |
| `quick_search`          | Fast search returning top 3-5 results             |
| `resolve_citation`      | Convert citation string to case record            |
| `search_cases_by_citation` | Find cases by citation or name                    |
| `lookup_case`           | Full case details with citation stats             |
| `get_citation_network`  | Traverse citation relationships (1-3 hops)        |
| `get_pricing`           | Check API credit costs                            |
```

--------------------------------

### Configure MCP Client with Vaquill

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/integrations/mcp.mdx

This JSON configuration snippet shows how to integrate the Vaquill MCP server into your client's MCP configuration file. It specifies the command to run Vaquill and sets the necessary environment variable for API key authentication. This setup allows AI assistants to leverage Vaquill's legal data capabilities.

```json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Rate Limiting and Exponential Backoff

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/errors.mdx

Guidance on handling rate limiting (429 errors) using exponential backoff with a Python example.

```APIDOC
## Rate Limiting and Exponential Backoff

### Description
When you receive a `429` (Rate Limited) status code, implement exponential backoff to avoid overwhelming the API and to ensure successful retries.

### Python Example
```python
import time
import requests

def search_with_retry(query, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.vaquill.ai/api/v1/research/search",
            headers={"Authorization": "Bearer vq_key_..."},
            json={"query": query}
        )
        if response.status_code == 429:
            time.sleep(2 ** attempt)
            continue
        return response
    raise Exception("Max retries exceeded")
```
```

--------------------------------

### Get Forward Citations using cURL

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Retrieves a list of cases that cite a given case (forward citations). This API call costs 1 credit and requires an Authorization header.

```bash
# Get forward citations (cases that cite this case) - costs 1 credit
curl https://api.vaquill.ai/api/v1/citations/{case_id}/cited-by \
  -H "Authorization: Bearer vq_key_..."
```

--------------------------------

### Authenticate API Requests with Bearer Token (JavaScript)

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

This JavaScript example shows how to perform an authenticated API request using the `fetch` API. It configures the request method, headers (including the Authorization Bearer token), and the request body as a JSON string.

```javascript
const response = await fetch("https://api.vaquill.ai/api/v1/research/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer vq_key_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ query: "right to privacy fundamental rights" })
});

const cases = await response.json();
```

--------------------------------

### Get Backward Citations using cURL

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Retrieves a list of cases that a given case cites (backward citations). This API call costs 1 credit and requires an Authorization header.

```bash
# Get backward citations (cases this case cites) - costs 1 credit
curl https://api.vaquill.ai/api/v1/citations/{case_id}/citations-of \
  -H "Authorization: Bearer vq_key_..."
```

--------------------------------

### Get Forward Citations API Request

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/guides/citations.mdx

This snippet demonstrates how to retrieve cases that cite a specific case using the Vaquill AI API. It sends a GET request to the '/api/v1/citations/{case_id}/cited-by' endpoint, where {case_id} is the unique identifier of the case.

```bash
curl https://api.vaquill.ai/api/v1/citations/{case_id}/cited-by \
  -H "Authorization: Bearer vq_key_..."
```

--------------------------------

### Get Backward Citations API Request

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/guides/citations.mdx

This snippet demonstrates how to retrieve cases cited by a specific case using the Vaquill AI API. It sends a GET request to the '/api/v1/citations/{case_id}/citations-of' endpoint, where {case_id} is the unique identifier of the case.

```bash
curl https://api.vaquill.ai/api/v1/citations/{case_id}/citations-of \
  -H "Authorization: Bearer vq_key_..."
```

--------------------------------

### GET /api/v1/citations/{case_id}

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Retrieve full details for a specific legal case using its unique ID. This includes citation treatment statistics and the case's freshness status (e.g., Good Law, Overruled). This lookup costs 2 credits.

```APIDOC
## GET /api/v1/citations/{case_id}

### Description
Get full case details including citation treatment statistics. Returns complete case record with freshness status (Good Law, Overruled, Distinguished, or Questioned).

### Method
GET

### Endpoint
https://api.vaquill.ai/api/v1/citations/{case_id}

### Parameters
#### Path Parameters
- **case_id** (string) - Required - The unique identifier for the case.

### Response
#### Success Response (200)
- **title** (string) - The title of the case.
- **court** (string) - The court where the case was heard.
- **date** (string) - The date of the judgment.
- **citations** (array) - An array of citation objects for the case.
- **freshness** (string) - The legal status of the case (e.g., "Good Law", "Overruled").
- **cited_by_count** (integer) - The number of other cases that cite this case.

#### Response Example
```json
{
  "title": "Case Title Example",
  "court": "Supreme Court",
  "date": "YYYY-MM-DD",
  "citations": [
    {
      "type": "SCC",
      "volume": "10",
      "reporter": "SCC",
      "page": "1"
    }
  ],
  "freshness": "Good Law",
  "cited_by_count": 150
}
```
```

--------------------------------

### GET /api/v1/citations/{case_id}/cited-by

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/guides/citations.mdx

Retrieves a list of cases that cite a specific case (forward citations).

```APIDOC
## GET /api/v1/citations/{case_id}/cited-by

### Description
Retrieves the cases that cite a specific case (forward citations).

### Method
GET

### Endpoint
https://api.vaquill.ai/api/v1/citations/{case_id}/cited-by

### Parameters
#### Path Parameters
- **case_id** (string) - Required - The unique identifier of the case.

### Response
#### Success Response (200)
- **citing_cases** (array) - An array of case objects that cite the specified case.
  - Each case object may contain fields like **title**, **court**, **date**, and **citations**.

#### Response Example
```json
{
  "citing_cases": [
    {
      "title": "Subsequent Case Title",
      "court": "Supreme Court",
      "date": "2020-05-15",
      "citations": [
        "(2020) 15 SCC 5"
      ]
    }
    // ... more citing cases
  ]
}
```
```

--------------------------------

### Lookup Full Case Details using Python

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

A Python function to fetch detailed information about a legal case given its ID. It makes a GET request to the Vaquill AI API and returns the case's metadata, including its freshness status.

```python
import requests

def lookup_case(case_id):
    response = requests.get(
        f"https://api.vaquill.ai/api/v1/citations/{case_id}",
        headers={"Authorization": "Bearer vq_key_..."}
    )
    return response.json()

case = lookup_case("some_case_id")
print(f"Title: {case['title']}")
print(f"Freshness: {case['freshness']}")  # Good Law, Overruled, Distinguished, Questioned
print(f"Times Cited: {case['cited_by_count']}")
```

--------------------------------

### GET /api/v1/citations/{case_id}/citations-of

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/guides/citations.mdx

Retrieves a list of cases that are cited by a specific case (backward citations).

```APIDOC
## GET /api/v1/citations/{case_id}/citations-of

### Description
Retrieves the cases cited by a specific case (backward citations).

### Method
GET

### Endpoint
https://api.vaquill.ai/api/v1/citations/{case_id}/citations-of

### Parameters
#### Path Parameters
- **case_id** (string) - Required - The unique identifier of the case.

### Response
#### Success Response (200)
- **cited_cases** (array) - An array of case objects that the specified case cites.
  - Each case object may contain fields like **title**, **court**, **date**, and **citations**.

#### Response Example
```json
{
  "cited_cases": [
    {
      "title": "Another Case Title",
      "court": "High Court",
      "date": "2010-01-01",
      "citations": [
        "(2010) 5 HC 1"
      ]
    }
    // ... more cited cases
  ]
}
```
```

--------------------------------

### Authenticate API Requests with Bearer Token

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

All API requests to Vaquill AI require a Bearer token in the Authorization header. API keys, prefixed with `vq_key_`, are generated from the dashboard settings. This example shows a basic authenticated POST request.

```bash
# Basic authenticated request
curl -X POST https://api.vaquill.ai/api/v1/research/search \
  -H "Authorization: Bearer vq_key_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "right to privacy fundamental rights"}'
```

--------------------------------

### Serve Documentation Locally with Mintlify

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/README.md

This command uses npx to run the Mintlify CLI for local development. It serves the documentation website at http://localhost:3000 with hot reloading capabilities, allowing for real-time updates during development.

```bash
npx mintlify dev
```

--------------------------------

### Run Vaquill MCP from Source

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/integrations/mcp.mdx

This bash script outlines the steps to clone the Vaquill MCP repository, set up its dependencies using uv, and run the server from the source code. It includes setting the API key as an environment variable before executing the Vaquill MCP command.

```bash
git clone https://github.com/Vaquill-AI/vaquill-mcp.git
cd vaquill-mcp
uv sync --all-extras
VAQUILL_API_KEY=vq_key_... uv run vaquill-mcp
```

--------------------------------

### Configure MCP Client with Vaquill Docs

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/integrations/mcp.mdx

This JSON configuration snippet demonstrates how to add Vaquill's documentation as an MCP server. This allows your AI assistant to query information directly from the Vaquill documentation, enabling it to answer questions about features, APIs, and configuration without requiring an API key.

```json
{
  "mcpServers": {
    "vaquill-docs": {
      "url": "https://vaquill.ai/docs/mcp"
    }
  }
}
```

--------------------------------

### Search Case Law with Filters (Bash)

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

This Bash command demonstrates how to search over 20 million cases using the Vaquill AI API. It supports natural language queries, Boolean operators, and filters such as court, year range, and limit. Each search costs 1 credit.

```bash
# Search with filters - costs 1 credit
curl -X POST https://api.vaquill.ai/api/v1/research/search \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "right to privacy fundamental rights",
    "court": "supreme_court",
    "year_from": 2015,
    "year_to": 2024,
    "limit": 10
  }'

# Boolean search examples:
# - "murder AND conviction" - both terms must appear
# - "Section 302 OR Section 304" - either term
# - "appeal NOT dismissed" - excludes term
# - "\"beyond reasonable doubt\"" - exact phrase
# - "(murder OR homicide) AND conviction" - grouped conditions
```

--------------------------------

### Search Cases with Vaquill AI API (Bash)

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/introduction.mdx

This snippet demonstrates how to search for cases using the Vaquill AI API via a cURL command. It requires an API key for authentication and sends a JSON payload with the search query and a limit for results. The response will contain relevant case information.

```bash
curl -X POST https://api.vaquill.ai/api/v1/research/search \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "right to privacy", "limit": 5}'
```

--------------------------------

### Set Environment Variables for MCP Server

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Sets environment variables required for the Vaquill MCP server. Includes the API key, optional base URL, and timeout settings. Also shows how to run the server from source for development purposes.

```bash
# Environment variables for MCP server
export VAQUILL_API_KEY="vq_key_..."       # Required
export VAQUILL_BASE_URL="https://api.vaquill.ai"  # Optional, default
export VAQUILL_TIMEOUT="120"              # Optional, seconds

# Run from source for development
git clone https://github.com/Vaquill-AI/vaquill-mcp.git
cd vaquill-mcp
uv sync --all-extras
VAQUILL_API_KEY=vq_key_... uv run vaquill-mcp
```

--------------------------------

### Search Case Law via API (Bash)

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/guides/case-law-research.mdx

This snippet demonstrates how to use the Vaquill AI search API to find relevant court cases. It requires an API key for authentication and accepts parameters like query, court, date range, and result limit. Each search consumes one credit.

```bash
curl -X POST https://api.vaquill.ai/api/v1/research/search \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "right to privacy fundamental rights",
    "court": "supreme_court",
    "year_from": 2015,
    "year_to": 2024,
    "limit": 10
  }'
```

--------------------------------

### Search Cases by Citation or Keyword using cURL

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Searches for legal cases using a query string, which can be a citation or a keyword. This API call costs 1 credit and requires an Authorization header.

```bash
# Search cases by citation or keyword - costs 1 credit
curl -X POST https://api.vaquill.ai/api/v1/citations/search \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "right to privacy", "limit": 10}'
```

--------------------------------

### Configure MCP Server for Vaquill

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Configuration snippet for the MCP server, specifying the command to run Vaquill and setting the required API key. This configuration is used by various AI clients like Claude Desktop, Cursor, and VS Code.

```json
// Add to your MCP config file:
// - Claude Desktop: claude_desktop_config.json
// - Claude Code: .claude/mcp.json or ~/.claude/mcp.json
// - Cursor: .cursor/mcp.json
// - VS Code: .vscode/mcp.json
// - Windsurf: ~/.windsurf/mcp.json

{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Traverse Citation Network using Python

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Provides Python functions to retrieve backward (cases cited by) and forward (cases citing) citations for a given case ID. Essential for understanding legal precedent and case relationships.

```python
import requests

def get_citations_of(case_id):
    """Get cases cited by this case (backward citations)"""
    response = requests.get(
        f"https://api.vaquill.ai/api/v1/citations/{case_id}/citations-of",
        headers={"Authorization": "Bearer vq_key_..."}
    )
    return response.json()

def get_cited_by(case_id):
    """Get cases that cite this case (forward citations)"""
    response = requests.get(
        f"https://api.vaquill.ai/api/v1/citations/{case_id}/cited-by",
        headers={"Authorization": "Bearer vq_key_..."}
    )
    return response.json()

# Build citation network
case_id = "some_case_id"
cited_cases = get_citations_of(case_id)    # What this case relies on
citing_cases = get_cited_by(case_id)       # What relies on this case

print(f"This case cites {len(cited_cases)} cases")
print(f"This case is cited by {len(citing_cases)} cases")
```

--------------------------------

### POST /api/v1/research/search

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Search 20M+ cases using natural language queries, Boolean operators, or citation strings. Supports filtering by court, year range, judge, and citation format. Returns case title, all known citations, court and date, bench composition, relevance score, and matching snippets.

```APIDOC
## POST /api/v1/research/search

### Description
Search over 20 million court cases using natural language queries, Boolean operators, or citation strings. This endpoint supports filtering by court, year range, judge, and citation format. The response includes the case title, all known citations, court and date information, bench composition, relevance score, and matching snippets.

### Method
POST

### Endpoint
`/api/v1/research/search`

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query. Can be natural language, Boolean operators, or citation strings.
- **court** (string) - Optional - Filters results by a specific court (e.g., "supreme_court").
- **year_from** (integer) - Optional - Filters results from a specific year.
- **year_to** (integer) - Optional - Filters results up to a specific year.
- **limit** (integer) - Optional - The maximum number of results to return (default is 10).

### Request Example
```bash
# Search with filters - costs 1 credit
curl -X POST https://api.vaquill.ai/api/v1/research/search \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{ 
    "query": "right to privacy fundamental rights",
    "court": "supreme_court",
    "year_from": 2015,
    "year_to": 2024,
    "limit": 10
  }'

# Boolean search examples:
# - "murder AND conviction" - both terms must appear
# - "Section 302 OR Section 304" - either term
# - "appeal NOT dismissed" - excludes term
# - "\"beyond reasonable doubt\"" - exact phrase
# - "(murder OR homicide) AND conviction" - grouped conditions
```

### Request Example (Python)
```python
import requests

def search_cases(query, court=None, year_from=None, year_to=None, limit=10):
    payload = {"query": query, "limit": limit}
    if court:
        payload["court"] = court
    if year_from:
        payload["year_from"] = year_from
    if year_to:
        payload["year_to"] = year_to

    response = requests.post(
        "https://api.vaquill.ai/api/v1/research/search",
        headers={"Authorization": "Bearer vq_key_..."},
        json=payload
    )
    return response.json()

# Natural language search
results = search_cases("cases where the court discussed the right to privacy as a fundamental right")

# Boolean search with filters
results = search_cases(
    query='(murder OR homicide) AND "supreme court"',
    court="supreme_court",
    year_from=2020,
    limit=5
)
```

### Response
#### Success Response (200)
- **title** (string) - The title of the case.
- **citations** (array of strings) - All known citation formats for the case.
- **court** (string) - The court where the case was decided.
- **date** (string) - The date of the decision.
- **bench** (array of strings) - The judges who sat on the bench.
- **relevance_score** (float) - A score indicating the relevance of the case to the query.
- **snippets** (array of strings) - Excerpts from the case that match the query.

#### Response Example
```json
{
  "cases": [
    {
      "title": "K.S. Puttaswamy v. Union of India",
      "citations": ["(2017) 10 SCC 1", "AIR 2017 SC 4161", "2017 INSC 1"],
      "court": "Supreme Court of India",
      "date": "2017-08-24",
      "bench": ["J.S. Khehar", "J. Chelameswar", "S.A. Bobde", "D.Y. Chandrachud", "Ashok Bhushan", "N.V. Ramana", "R.F. Nariman", "A.K. Sikri", "S.K. Kaul"],
      "relevance_score": 0.95,
      "snippets": ["The right to privacy is an integral part of the Right to Life and Personal Liberty guaranteed in Article 21 of the Constitution."]
    }
  ]
}
```
```

--------------------------------

### Search Cases API Request

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/guides/citations.mdx

This snippet shows how to search for cases using the Vaquill AI API. It sends a POST request with a query string and an optional limit to the '/api/v1/citations/search' endpoint. The search can be performed by title, keyword, or topic.

```bash
curl -X POST https://api.vaquill.ai/api/v1/citations/search \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "right to privacy", "limit": 10}'
```

--------------------------------

### Resolve Citation Strings (Bash)

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

This Bash command uses the Vaquill AI API to resolve citation strings into full case records. It supports SCC, AIR, and INSC formats and returns the canonical case details, including all known citation formats. Resolving a citation costs 1 credit.

```bash
# Resolve a citation - costs 1 credit
curl -X POST https://api.vaquill.ai/api/v1/citations/resolve \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{"citation": "(2017) 10 SCC 1"}'

# Returns K.S. Puttaswamy v. Union of India with all citation formats:
# - SCC: (2017) 10 SCC 1
# - AIR: AIR 2017 SC 4161
# - INSC: 2017 INSC 1
```

--------------------------------

### Lookup Full Case Details using cURL

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Retrieves comprehensive details for a specific legal case using its unique ID. This API call costs 2 credits and requires an Authorization header.

```bash
# Lookup full case details - costs 2 credits
curl https://api.vaquill.ai/api/v1/citations/{case_id} \
  -H "Authorization: Bearer vq_key_..."
```

--------------------------------

### Search Cases by Citation or Keyword using Python

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Provides a Python function to search for legal cases by topic or case name. It sends a POST request to the Vaquill AI API and returns the JSON response containing matching cases.

```python
import requests

def search_citations(query, limit=10):
    response = requests.post(
        "https://api.vaquill.ai/api/v1/citations/search",
        headers={"Authorization": "Bearer vq_key_..."},
        json={"query": query, "limit": limit}
    )
    return response.json()

# Search by topic
cases = search_citations("right to privacy", limit=10)

# Search by case name
cases = search_citations("Kesavananda Bharati", limit=5)
```

--------------------------------

### Vaquill AI API Endpoints

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Reference for Vaquill AI API endpoints, including their methods, credit costs, and descriptions.

```APIDOC
## Vaquill AI API Endpoints

### Search Legal Cases

- **Method**: POST
- **Endpoint**: `/api/v1/research/search`
- **Description**: Performs a boolean keyword search for legal cases with filters.
- **Credits**: 1

### Resolve Citation

- **Method**: POST
- **Endpoint**: `/api/v1/citations/resolve`
- **Description**: Converts a citation string to a case record.
- **Credits**: 1

### Search Cases by Citation

- **Method**: POST
- **Endpoint**: `/api/v1/citations/search`
- **Description**: Finds cases by citation or name.
- **Credits**: 1

### Get Case Details

- **Method**: GET
- **Endpoint**: `/api/v1/citations/{case_id}`
- **Description**: Retrieves full case details with citation statistics.
- **Credits**: 2

### Get Cases Citing This Case

- **Method**: GET
- **Endpoint**: `/api/v1/citations/{case_id}/cited-by`
- **Description**: Retrieves cases that cite the specified case.
- **Credits**: 1

### Get Cases Cited By This Case

- **Method**: GET
- **Endpoint**: `/api/v1/citations/{case_id}/citations-of`
- **Description**: Retrieves cases cited by the specified case.
- **Credits**: 1

### Get Pricing Information

- **Method**: GET
- **Endpoint**: `/api/v1/pricing` (Assumed endpoint for pricing, not explicitly listed but implied by `get_pricing` tool)
- **Description**: Check API credit costs.
- **Credits**: Free
```

--------------------------------

### API Credit Costs

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/credits.mdx

This section details the credit cost for each available API endpoint. Note that the cost is per API call.

```APIDOC
## API Credit Costs

### Description
This documentation outlines the credit cost associated with each Vaquill AI API endpoint. The credit cost is applied per individual API call.

### Costs by Endpoint

| Endpoint | Method |
|----------|--------|
| `/api/v1/research/search` | POST |
| `/api/v1/citations/resolve` | POST |
| `/api/v1/citations/search` | POST |
| `/api/v1/citations/{case_id}` | GET |
| `/api/v1/citations/{case_id}/cited-by` | GET |
| `/api/v1/citations/{case_id}/citations-of` | GET |

### Notes
- Each API call consumes a fixed number of credits.
- New accounts receive 10 free credits upon creation.
- Credit cost is applied per call, irrespective of the size of the returned data.

### Checking Your Balance

Remaining credits can be viewed in your [dashboard](https://app.vaquill.ai/settings). API calls will return a `403` status code when your credits reach zero.

### Subscription Plans

| Plan | Credits | Best For |
|---|---|---|
| Free | 10 | Evaluation |
| Starter | 100/month | Individual developers |
| Professional | 500/month | Small teams |
| Business | 2,000/month | Production use |
| Enterprise | Custom | High-volume integrations |

### Credit Expiration

Monthly credits are reset at the beginning of your billing cycle. Unused credits do not carry over to the next cycle.
```

--------------------------------

### Implement Exponential Backoff for API Retries in Python

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Demonstrates how to implement robust error handling for API requests in Python, specifically focusing on rate limiting (429 status code) using exponential backoff. It also handles other common HTTP errors like authentication and validation failures.

```python
import time
import requests

def search_with_retry(query, max_retries=3):
    """Search with exponential backoff for rate limiting"""
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.vaquill.ai/api/v1/research/search",
            headers={"Authorization": "Bearer vq_key_..."},
            json={"query": query}
        )

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 401:
            raise Exception("Invalid or missing API key")
        elif response.status_code == 403:
            raise Exception("Insufficient credits - purchase more at app.vaquill.ai/settings")
        elif response.status_code == 422:
            # Validation error - check field details
            error = response.json()
            raise Exception(f"Validation error: {error['detail']}")
        elif response.status_code == 429:
            # Rate limited - exponential backoff
            time.sleep(2 ** attempt)
            continue
        elif response.status_code >= 500:
            # Server error - retry
            time.sleep(2 ** attempt)
            continue
        else:
            raise Exception(f"Unexpected error: {response.status_code}")

    raise Exception("Max retries exceeded")

# Error response format:
```

--------------------------------

### Troubleshooting Common Issues

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/errors.mdx

Solutions for frequently encountered problems such as authentication failures, credit issues, and validation errors.

```APIDOC
## Troubleshooting Common Issues

### Description
This section provides solutions for common problems encountered when using the Vaquill AI API.

### 401 Unauthorized but my key is correct
Ensure you are including the `Bearer` prefix before your API key in the `Authorization` header. The key alone is not sufficient.
Example: `Authorization: Bearer vq_key_...`

### 403 Forbidden after purchasing credits
Credit purchases may take a few moments to be reflected in your account. Please wait a short period and retry your request.

### 422 Validation Error
1. Ensure you are setting the `Content-Type` header to `application/json`.
2. Examine the `detail` field in the error response. The `loc` field within each error object indicates the specific field (in the request body or query parameters) that caused the validation failure.
```

--------------------------------

### Citation Network API

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Explore the citation graph to find relationships between cases. Retrieve cases cited by a specific case (backward citations) or cases that cite it (forward citations). This is crucial for understanding legal precedent and case freshness. Each query costs 1 credit.

```APIDOC
## Citation Network API

### Description
Traverse the citation graph to find cases cited by a case (backward citations) or cases that cite it (forward citations). Essential for understanding legal precedent relationships and case freshness.

### Method
GET

### Endpoints
- **Backward Citations:** https://api.vaquill.ai/api/v1/citations/{case_id}/citations-of
- **Forward Citations:** https://api.vaquill.ai/api/v1/citations/{case_id}/cited-by

### Parameters
#### Path Parameters
- **case_id** (string) - Required - The unique identifier for the case.

### Response
#### Success Response (200)
- **citations** (array) - An array of citation objects representing the related cases.

#### Response Example (Backward Citations)
```json
[
  {
    "title": "Previous Case Title",
    "court": "Appellate Court",
    "date": "YYYY-MM-DD",
    "citations": [
      {
        "type": "AIR",
        "volume": "2017",
        "reporter": "AIR",
        "page": "4161"
      }
    ]
  }
]
```

#### Response Example (Forward Citations)
```json
[
  {
    "title": "Subsequent Case Title",
    "court": "Supreme Court",
    "date": "YYYY-MM-DD",
    "citations": [
      {
        "type": "SCC",
        "volume": "10",
        "reporter": "SCC",
        "page": "1"
      }
    ]
  }
]
```
```

--------------------------------

### POST /api/v1/citations/search

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/guides/citations.mdx

Searches for cases based on a query string, which can include titles, keywords, or topics. Allows specifying a limit for the number of results.

```APIDOC
## POST /api/v1/citations/search

### Description
Searches for cases by title, keyword, or topic.

### Method
POST

### Endpoint
https://api.vaquill.ai/api/v1/citations/search

### Parameters
#### Request Body
- **query** (string) - Required - The search query (e.g., "right to privacy").
- **limit** (integer) - Optional - The maximum number of results to return (default is 10).

### Request Example
```json
{
  "query": "right to privacy",
  "limit": 10
}
```

### Response
#### Success Response (200)
- **cases** (array) - An array of case objects matching the search query.
  - Each case object may contain fields like **title**, **court**, **date**, and **citations**.

#### Response Example
```json
{
  "cases": [
    {
      "title": "K.S. Puttaswamy v. Union of India",
      "court": "Supreme Court of India",
      "date": "2017-08-24",
      "citations": [
        "(2017) 10 SCC 1",
        "AIR 2017 SC 4161",
        "2017 INSC 1"
      ]
    }
    // ... more cases
  ]
}
```
```

--------------------------------

### Authenticate API Requests with Bearer Token (Python)

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

This Python snippet demonstrates how to make an authenticated API request using the `requests` library. It includes setting the Authorization header with a Bearer token and the Content-Type, along with sending a JSON payload for a search query.

```python
import requests

response = requests.post(
    "https://api.vaquill.ai/api/v1/research/search",
    headers={
        "Authorization": "Bearer vq_key_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={"query": "right to privacy fundamental rights"}
)

# Response contains matching cases with citations, court info, and relevance scores
cases = response.json()
```

--------------------------------

### Search Case Law with Filters (Python)

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

This Python function `search_cases` allows users to query the Vaquill AI case law database with various filters. It supports natural language and Boolean queries, and can filter by court, year range, and result limit. The function returns the search results as JSON.

```python
import requests

def search_cases(query, court=None, year_from=None, year_to=None, limit=10):
    payload = {"query": query, "limit": limit}
    if court:
        payload["court"] = court
    if year_from:
        payload["year_from"] = year_from
    if year_to:
        payload["year_to"] = year_to

    response = requests.post(
        "https://api.vaquill.ai/api/v1/research/search",
        headers={"Authorization": "Bearer vq_key_..."},
        json=payload
    )
    return response.json()

# Natural language search
results = search_cases("cases where the court discussed the right to privacy as a fundamental right")

# Boolean search with filters
results = search_cases(
    query='(murder OR homicide) AND "supreme court"',
    court="supreme_court",
    year_from=2020,
    limit=5
)
```

--------------------------------

### Resolve Legal Citations in Python

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

Resolves various legal citation formats (SCC, AIR, INSC) into a standardized case object with full metadata. This function is crucial for parsing and standardizing legal references.

```python
case = resolve_citation("(2017) 10 SCC 1")      # SCC format
case = resolve_citation("AIR 2017 SC 4161")     # AIR format
case = resolve_citation("2017 INSC 1")          # INSC format

# All return the same case with full metadata
print(f"Case: {case['title']}")
print(f"Court: {case['court']}")
print(f"Date: {case['date']}")
print(f"Citations: {case['citations']}")
```

--------------------------------

### Resolve Citation Strings (Python)

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

This Python function `resolve_citation` takes a citation string as input and uses the Vaquill AI API to find the corresponding full case record. It handles various citation formats and returns the canonical case information, including all known citation strings.

```python
import requests

def resolve_citation(citation_string):
    response = requests.post(
        "https://api.vaquill.ai/api/v1/citations/resolve",
        headers={"Authorization": "Bearer vq_key_..."},
        json={"citation": citation_string}
    )
    return response.json()

```

--------------------------------

### Authentication

Source: https://context7.com/vaquill-ai/vaquill-ai-docs/llms.txt

All API requests require a Bearer token in the Authorization header. API keys use the `vq_key_` prefix.

```APIDOC
## Authentication

All API requests require a Bearer token in the Authorization header. API keys use the `vq_key_` prefix and are generated from the dashboard settings.

### Request Example (cURL)
```bash
curl -X POST https://api.vaquill.ai/api/v1/research/search \
  -H "Authorization: Bearer vq_key_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "right to privacy fundamental rights"}'
```

### Request Example (Python)
```python
import requests

response = requests.post(
    "https://api.vaquill.ai/api/v1/research/search",
    headers={
        "Authorization": "Bearer vq_key_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={"query": "right to privacy fundamental rights"}
)

# Response contains matching cases with citations, court info, and relevance scores
cases = response.json()
```

### Request Example (JavaScript)
```javascript
const response = await fetch("https://api.vaquill.ai/api/v1/research/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer vq_key_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ query: "right to privacy fundamental rights" })
});

const cases = await response.json();
```
```

--------------------------------

### POST /api/v1/citations/resolve

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/guides/citations.mdx

Resolves a given citation string to retrieve the full case record, including court, date, bench, and all known citation strings for that case.

```APIDOC
## POST /api/v1/citations/resolve

### Description
Resolves a citation string to get the full case record.

### Method
POST

### Endpoint
https://api.vaquill.ai/api/v1/citations/resolve

### Parameters
#### Request Body
- **citation** (string) - Required - The citation string to resolve (e.g., "(2017) 10 SCC 1").

### Request Example
```json
{
  "citation": "(2017) 10 SCC 1"
}
```

### Response
#### Success Response (200)
- **case_record** (object) - Contains details of the resolved case.
  - **title** (string) - The title of the case.
  - **court** (string) - The court where the case was heard.
  - **date** (string) - The date of the decision.
  - **bench** (string) - The judges on the bench.
  - **citations** (array) - An array of all known citation strings for the case.

#### Response Example
```json
{
  "case_record": {
    "title": "K.S. Puttaswamy v. Union of India",
    "court": "Supreme Court of India",
    "date": "2017-08-24",
    "bench": "J.S. Khehar, C.J.I., J. Chelameswar, S.A. Bobde, R.K. Agrawal, N.V. Ramana, R.F. Nariman, A.M. Sapre, D.Y. Chandrachud, S.K. Kaul, S. Abdul Nazeer, R. Banumathi, JJ.",
    "citations": [
      "(2017) 10 SCC 1",
      "AIR 2017 SC 4161",
      "2017 INSC 1"
    ]
  }
}
```
```

--------------------------------

### Python Rate Limiting with Exponential Backoff

Source: https://github.com/vaquill-ai/vaquill-ai-docs/blob/main/errors.mdx

This Python snippet demonstrates how to implement exponential backoff when encountering a 429 Rate Limited status code from the Vaquill AI API. It uses the `requests` library and includes a maximum retry count.

```python
import time
import requests

def search_with_retry(query, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.vaquill.ai/api/v1/research/search",
            headers={"Authorization": "Bearer vq_key_..."},
            json={"query": query}
        )
        if response.status_code == 429:
            time.sleep(2 ** attempt)
            continue
        return response
    raise Exception("Max retries exceeded")
```