Pi Kagi API

Official Kagi 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 the HTML search page.

Requirements

• Node.js + npm
• Pi CLI
• A Kagi API key from the Kagi API dashboard

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

Option 1: Install from npm (recommended)

Once the package is published to npm, install it through Pi's npm package specifier:

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

If it is not published yet, use Option 2 or 3 below.

Option 2: Install via git

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

Option 3: Manual Installation

Clone this repository to your Pi extensions directory:

cd ~/.pi/agent/extensions
git clone https://github.com/mjakl/pi-kagi-api.git
cd pi-kagi-api
npm install

Configuration

Get an API key

1. Open the Kagi API dashboard
2. Generate an API key
3. Configure it using one of the options below

Option 1: Environment variable

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:

/kagi-api-login

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

By default that file is:

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

If you customized Pi's agent config directory with PI_CODING_AGENT_DIR, the file is stored there instead:

$PI_CODING_AGENT_DIR/kagi-api.json

The file format is:

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

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

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:

{
  "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:

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

Kagi Extract currently requires HTTPS URLs.

Optional extraction

kagi_extract is intentionally separate from kagi_search.

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

Pi can enable or disable tools natively with --tools. For example:

# Enable search but not extraction
pi --tools read,write,edit,bash,kagi_search

# Enable both search and extraction
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:

npm install

Type-check:

npm run typecheck

Check what would be published:

npm pack --dry-run
npm publish --dry-run

Release to npm:

npm publish --access public

Manual Pi check:

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

Then invoke kagi_search or kagi_extract from Pi.

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 the official Kagi 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.

License

MIT