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

# Chrome Extension

> Statute search assistant as a Manifest V3 Chrome extension. Calls the Vaquill API directly with the user's own API key - no proxy server required.

A Manifest V3 Chrome extension that puts Vaquill's statute search in any browser tab. The popup calls `api.vaquill.ai` directly using the user's own API key - no proxy server, no backend to run, no infrastructure to maintain. Works in any Chromium-based browser (Chrome, Edge, Brave, Arc, Opera). The public API covers US statutes only: the US Code, the CFR, all 50 state statute codes, the U.S. Constitution, the Federal Rules, and Executive Orders.

Source: [github.com/Vaquill-AI/integrations/chrome-extension](https://github.com/Vaquill-AI/integrations/tree/main/chrome-extension).

## What you get

* Manifest V3, service-worker based
* Direct calls to `api.vaquill.ai` - no middleware
* BYOK (bring your own key): each user configures their own API key in the Options page
* Structured statute source cards: title or code, section number, jurisdiction, heading, excerpt
* Vanilla JavaScript, no build step - edit and reload

## Prerequisites

* Google Chrome (or any Chromium-based browser) version 110+
* A Vaquill API key (`vq_key_...`) from [app.vaquill.ai/settings/api](https://app.vaquill.ai/settings/api). See [Authentication](/docs/api-guide/authentication).

## Quickstart

<Steps>
  <Step title="Clone the repo">
    ```bash theme={"theme":"github-dark"}
    git clone https://github.com/Vaquill-AI/integrations.git
    cd integrations/chrome-extension
    ```
  </Step>

  <Step title="Load the extension">
    1. Open `chrome://extensions/`
    2. Toggle **Developer mode** on (top right)
    3. Click **Load unpacked**
    4. Select the `extension/` folder
  </Step>

  <Step title="Configure your API key">
    1. Right-click the Vaquill icon in the toolbar and choose **Options** (or click the gear icon inside the popup)
    2. Paste your API key (`vq_key_...`)
    3. Choose a default **Jurisdiction**
    4. Click **Save**
  </Step>

  <Step title="Test">
    Click the extension icon and try a search like *"42 USC 1983"* or *"FRCP Rule 12"*. Expand a source card to see the section number, jurisdiction, heading, and excerpt.
  </Step>
</Steps>

## Configuration

### Extension defaults

Edit `extension/js/config.js`:

| Setting               | Description                                              |
| --------------------- | -------------------------------------------------------- |
| `API_URL`             | Vaquill API base URL (default: `https://api.vaquill.ai`) |
| `MAX_SOURCES`         | Maximum number of statute sections returned per query    |
| `SUGGESTED_QUESTIONS` | Array of starter searches shown on the welcome screen    |

### Per-user settings (stored in `chrome.storage.local`)

| Setting      | Description                                              |
| ------------ | -------------------------------------------------------- |
| API Key      | The user's Vaquill API key, entered via the Options page |
| Jurisdiction | Preferred jurisdiction for search context                |

<Info>
  API keys live in `chrome.storage.local` on the user's device. The extension never transmits them anywhere except to `api.vaquill.ai`.
</Info>

## API contract

The extension calls a single endpoint:

```
POST https://api.vaquill.ai/api/v1/statutes/search
Authorization: Bearer vq_key_...
Content-Type: application/json
```

Request body:

```json theme={"theme":"github-dark"}
{
  "query": "42 USC 1983",
  "limit": 5
}
```

Full schema in the [Statute search API reference](/docs/api-reference/statutes/search-us-statutes).

## Project layout

```
extension/
  manifest.json          Chrome extension manifest (v3)
  popup.html             Main chat popup
  options.html           Settings page (API key, mode, jurisdiction)
  css/popup.css          All styles (CSS custom properties for theming)
  icons/                 16, 48, 128 px icons
  js/
    config.js            API URL, defaults, suggested questions
    session.js           Storage manager (API key, chat history)
    background.js        Service worker - calls POST /api/v1/statutes/search
    popup.js             Search UI logic, source rendering
    markdown.js          Lightweight markdown-to-HTML renderer
    options.js           Settings page logic
```

## Branding and theming

### Name and description

Edit `extension/manifest.json`:

```json theme={"theme":"github-dark"}
{
  "name": "Vaquill Statute Search",
  "description": "Statute search assistant for US Code, CFR, and all 50 state statute codes",
  "version": "1.0.0"
}
```

### Icons

Place PNGs in `extension/icons/`:

* `icon16.png` (16x16) - toolbar
* `icon48.png` (48x48) - extensions page
* `icon128.png` (128x128) - Chrome Web Store listing

### Colors

Edit CSS custom properties at the top of `extension/css/popup.css`:

```css theme={"theme":"github-dark"}
:root {
  --primary-color: #8b5cf6;
  --primary-hover: #7c3aed;
  /* ... */
}
```

## Host permissions

`host_permissions` in `manifest.json` must match the API domain the extension calls.

**Default (Vaquill production API):**

```json theme={"theme":"github-dark"}
"host_permissions": [
  "https://api.vaquill.ai/*"
]
```

**Custom API domain:**

```json theme={"theme":"github-dark"}
"host_permissions": [
  "https://api.yourdomain.com/*"
]
```

**Multiple domains (dev + production):**

```json theme={"theme":"github-dark"}
"host_permissions": [
  "http://localhost:8000/*",
  "https://api.vaquill.ai/*"
]
```

<Warning>
  Always use specific domains rather than wildcards (`https://*/*`). The Chrome Web Store reviews extensions with broad host permissions more aggressively and may reject them.
</Warning>

## Publishing to the Chrome Web Store

### Prerequisites

1. A Google Developer account (\$5 USD one-time fee)
2. Register at [chrome.google.com/webstore/devconsole](https://chrome.google.com/webstore/devconsole/)

### Preparation checklist

* Set the production `API_URL` in `config.js`
* Update `manifest.json` with name, description, version, and `host_permissions`
* Add extension icons (16, 48, 128 px)
* Prepare at least one screenshot (1280x800 px)
* Prepare a privacy policy URL (required by Google)

### Package the extension

```bash theme={"theme":"github-dark"}
cd extension/
zip -r vaquill-extension.zip . -x "*.DS_Store" "*.git*"
```

### Upload

<Steps>
  <Step title="Open the dashboard">
    Go to the [Chrome Web Store Developer Dashboard](https://chrome.google.com/webstore/devconsole/).
  </Step>

  <Step title="Create a new item">
    Click **New Item** and upload `vaquill-extension.zip`.
  </Step>

  <Step title="Fill out the listing">
    * **Name**: Vaquill Statute Search
    * **Summary**: Statute search assistant for US Code, CFR, and 50 states (132 chars max)
    * **Description**: Full feature description
    * **Category**: Productivity
    * **Language**: English
    * **Screenshots**: At least 1 (1280x800 px)
    * **Privacy Policy**: URL to your privacy policy
    * **Permissions Justification**: Explain why `storage` and `activeTab` are needed
  </Step>

  <Step title="Submit for review">
    Typical review time: 1-3 business days.
  </Step>
</Steps>

## Development

The extension uses vanilla JavaScript with no build step. Edit files directly, then reload the extension at `chrome://extensions/` (click the refresh icon on the extension card).

## Troubleshooting

**"Failed to fetch" errors**

* `host_permissions` in `manifest.json` does not match the API URL in `config.js`. Make both point to the same domain (e.g., `https://api.vaquill.ai`).

**API key not working**

* Generate a new key at [app.vaquill.ai/settings/api](https://app.vaquill.ai/settings/api) and re-enter it in the Options page.
* Check you have credits at [app.vaquill.ai/billing](https://app.vaquill.ai/billing).

**Extension not loading**

* Validate JSON syntax in `manifest.json`.
* Ensure all required Manifest V3 fields are present (`manifest_version: 3`, `name`, `version`, `action`, `background.service_worker`).

**No sources in responses**

* Try a more specific query (cite a statute by title and section number).
* Verify `MAX_SOURCES` is greater than 0 in `config.js`.

**Content Security Policy errors**

* Do not add inline scripts or external script sources.
* Restore the default CSP in `manifest.json`:

  ```json theme={"theme":"github-dark"}
  "content_security_policy": {
    "extension_pages": "script-src 'self'; object-src 'self'"
  }
  ```

## Related

<CardGroup cols={2}>
  <Card title="Statute search API" icon="message" href="/docs/api-reference/statutes/search-us-statutes">
    The endpoint this extension calls.
  </Card>

  <Card title="Authentication" icon="key" href="/docs/api-guide/authentication">
    How to generate and rotate API keys.
  </Card>

  <Card title="Embedded Chat Widget" icon="bolt" href="/docs/integrations/widgets/embedded-chat">
    Drop the same chat into any website via iframe.
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/Vaquill-AI/integrations/tree/main/chrome-extension">
    Source code and issue tracker.
  </Card>
</CardGroup>