---
slug: "mjakl-pi-kagi-api"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/mjakl/pi-kagi-api@main/README.md"
repo: "https://github.com/mjakl/pi-kagi-api"
source_file: "README.md"
branch: "main"
---
# Pi Kagi API

**Official Kagi Search and Extract API tools for the Pi coding agent.**

This extension provides:

- `kagi_search` — web search via the official Kagi Search API
- `kagi_extract` — HTTPS page extraction as markdown via the official Kagi Extract API

It is the official-API successor to the legacy `pi-kagi-search` extension, which used a Kagi session token and parsed Kagi's HTML search page.

## User Guide

### Why Pi Kagi API

Use this package when Pi needs current web research through Kagi's official API. Search returns Kagi web results; extraction is separate so full page reads happen only when needed.

### Requirements

- Node.js + npm
- Pi CLI
- A Kagi API key from the [Kagi API dashboard](https://kagi.com/api/keys)

Kagi API usage may incur charges according to Kagi's API pricing. `kagi_extract` is a separate tool because extraction can incur additional API cost.

### Install

Install from npm:

```bash
pi install npm:@mjakl/pi-kagi-api
```

Install from git:

```bash
pi install git:github.com/mjakl/pi-kagi-api
```

Or install from a local checkout:

```bash
pi install /path/to/pi-kagi-api
```

Package name: `@mjakl/pi-kagi-api`.

### Configure an API key

1. Open the [Kagi API dashboard](https://kagi.com/api/keys).
2. Generate an API key.
3. Configure it using one of the options below.

#### Option 1: Environment variable

```bash
export KAGI_API_KEY="your-api-key-here"
```

Add it to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) to persist it.

#### Option 2: Interactive login

Start Pi and run:

```text
/kagi-api-login
```

This stores the key in Pi's agent config directory as `kagi-api.json`.

Default path:

```text
~/.pi/agent/kagi-api.json
```

If `PI_CODING_AGENT_DIR` is set:

```text
$PI_CODING_AGENT_DIR/kagi-api.json
```

The file format is:

```json
{
  "apiKey": "your-api-key-here"
}
```

The extension writes this file with restrictive permissions (`0600`) where supported.

### Typical use

Ask Pi to search first, then extract only the most relevant pages:

```text
Search Kagi for the current Kagi Search API documentation.
Extract the official docs page and summarize the parameters.
```

Search does not fetch full page contents unless the agent explicitly calls `kagi_extract`. This keeps API usage predictable and avoids surprise extraction charges.

### Migration from `pi-kagi-search`

The older `pi-kagi-search` extension used a Kagi session token and parsed Kagi's HTML search page. This package uses Kagi's official API instead.

Recommended migration:

1. Install `@mjakl/pi-kagi-api`.
2. Configure `KAGI_API_KEY` or run `/kagi-api-login`.
3. Remove or disable the old `pi-kagi-search` package to avoid duplicate `kagi_search` tools.

### Security note

Your Kagi API key can spend API credits. Treat it like a password and do not commit `kagi-api.json` to version control.

---

## Technical Reference

These sections document tool parameters, allowlisting behavior, and development commands.

### Tools

| Tool | Description |
|------|-------------|
| `kagi_search` | Search the web using the official Kagi Search API. |
| `kagi_extract` | Extract HTTPS page contents as markdown using the official Kagi Extract API. |

### `kagi_search`

Parameters:

- `query` — search query.
- `limit` — optional result limit, 1–50, default 10.

Example:

```json
{
  "query": "Kagi Search API documentation",
  "limit": 5
}
```

### `kagi_extract`

Parameters:

- `urls` — array of 1–10 HTTPS URLs.
- `timeout` — optional extraction timeout in seconds, 0.5–10.

Example:

```json
{
  "urls": ["https://help.kagi.com/kagi/api/search.html"],
  "timeout": 4
}
```

Kagi Extract currently requires HTTPS URLs.

### Tool allowlisting

Pi can enable or disable tools natively with `--tools`.

Enable search but not extraction:

```bash
pi --tools read,write,edit,bash,kagi_search
```

Enable both search and extraction:

```bash
pi --tools read,write,edit,bash,kagi_search,kagi_extract
```

`--tools` is an allowlist, so include any built-in tools you still want available.

### Local development

Install dependencies:

```bash
npm install
```

Type-check:

```bash
npm run typecheck
```

Check what would be published:

```bash
npm pack --dry-run
npm publish --dry-run
```

Manual Pi check:

```bash
KAGI_API_KEY="your-api-key" pi -e .
```

Then invoke `kagi_search` or `kagi_extract` from Pi.

### Release

Release to npm:

```bash
npm publish --access public
```

## License

MIT