---
name: aiqel
description: >-
  Search and grow AIqel's processed knowledge base. Use when you need to find
  insights, transcripts, translations or tags across podcasts/text that AIqel
  has processed, or to push new content (an audio URL or raw text) into AIqel to
  be transcribed, translated (karaoke-synced) and tagged. Trigger when the user
  asks to "search AIqel", "look up what a podcast said about X", "add this
  episode/audio/text to AIqel", "follow this podcast", or to check processing
  status of an item.
---

# AIqel — knowledge search & ingestion

AIqel ingests content (podcasts, text), transcribes it, translates it with
karaoke sync, and extracts tagged insight blocks. This skill teaches you to
**pull** that knowledge and **push** new content to it.

## Two ways to call it

- **MCP tools** (preferred for agents) — the `@aiqel/mcp` server exposes tools
  over stdio. Requires `AIQEL_API_URL` and `AIQEL_API_KEY`. See `docs/MCP.md`.
- **REST API** — `/v1/*` endpoints, Bearer API key auth. See `docs/API.md`.

Get an API key by minting one (admin endpoint `POST /admin/api-keys` with the
`x-admin-token` header, or `tsx packages/db/prisma/create-api-key.ts`).

## MCP tools

| Tool               | Use it to…                                                      |
| ------------------ | --------------------------------------------------------------- |
| `search_knowledge` | Search insights/transcripts/translations/tags — `{ query }`     |
| `add_item`         | Add audio (`{ type:'audio', audioUrl }`) or text (`{ type:'text', text }`) |
| `get_item`         | Pull an item's status + transcript + translations + insights — `{ id }` |
| `list_items`       | Poll items, optionally by `status` — `{ status?, limit? }`      |
| `add_source`       | Follow a source — `{ type, url?, title }`                       |

## When to use which

- **"What did X say about Y?" / find a quote or insight** → `search_knowledge`,
  then `get_item` on a hit's `itemId` for full context.
- **"Process this episode / add this text"** → `add_item`. Audio needs
  `audioUrl`; text needs `text`. You get back `{ id, status }`.
- **"Is it done yet?"** → poll `list_items` or `get_item` until status is
  `translated` / `enriched`.
- **"Follow this podcast/site"** → `add_source`.

## Push → poll → pull

1. `add_item` → returns `{ id, status }`.
2. `list_items` / `get_item` until the item reaches a terminal status.
3. `get_item` to read the transcript, translations and tagged insight blocks.

## REST equivalents (no MCP client)

```bash
# search
curl -X POST "$AIQEL_API_URL/v1/search" -H "Authorization: Bearer $AIQEL_API_KEY" \
  -H 'Content-Type: application/json' -d '{ "q": "creativity" }'

# add text
curl -X POST "$AIQEL_API_URL/v1/items" -H "Authorization: Bearer $AIQEL_API_KEY" \
  -H 'Content-Type: application/json' -d '{ "type": "text", "text": "…" }'

# pull an item
curl "$AIQEL_API_URL/v1/items/<id>" -H "Authorization: Bearer $AIQEL_API_KEY"
```

Full endpoint reference: `docs/API.md`. MCP setup: `docs/MCP.md`.