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

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:

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

Install from git:

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

Or install from a local checkout:

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

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

Configure 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.

Default path:

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

If PI_CODING_AGENT_DIR is set:

$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.

Typical use

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

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:

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

Tool allowlisting

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

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

Manual Pi check:

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

Then invoke kagi_search or kagi_extract from Pi.

Release

Release to npm:

npm publish --access public

License

MIT