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

# Knowledge base

KB articles, hybrid search, and on-demand ingestion via the v1 API.

# Knowledge base API

The agent retrieves relevant articles automatically when answering
conversations. You can also drive ingestion + lookup directly.

## Endpoints

| Method | Path | Scope |
|--------|------|-------|
| `GET` | `/v1/projects/{projectId}/kb/articles` | `read` |
| `POST` | `/v1/projects/{projectId}/kb/articles` | `kb:write` |
| `GET` | `/v1/projects/{projectId}/kb/articles/{articleId}` | `read` |
| `PATCH` | `/v1/projects/{projectId}/kb/articles/{articleId}` | `kb:write` |
| `DELETE` | `/v1/projects/{projectId}/kb/articles/{articleId}` | `kb:write` |
| `POST` | `/v1/projects/{projectId}/kb/articles/{articleId}/publish` | `kb:write` |
| `GET` | `/v1/projects/{projectId}/kb/search?q=...` | `read` |

## List articles

```bash cURL
curl 'https://api.rogeriq.com/api/v1/projects/prj_xxx/kb/articles?status=published&limit=20' \
  -H "X-API-Key: riq_xxx"
```

```bash CLI
rogeriq kb list --limit 20
```

```ts SDK
const page = await roger.kb.list({ limit: 20 });
```

Filters: `status` (`draft`/`published`/`archived`), `category`, `q`,
`cursor`, `limit`, `sort`, `order`. Returns
`{ data, cursor, has_more }`.

## Create an article

```bash cURL
curl -X POST https://api.rogeriq.com/api/v1/projects/prj_xxx/kb/articles \
  -H "X-API-Key: riq_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How refunds work",
    "content": "Customers can request a refund within 30 days...",
    "status": "published",
    "is_public": true,
    "category": "billing"
  }'
```

```bash CLI
rogeriq kb create --title "How refunds work" --content-file ./refunds.md --status published
```

```ts SDK
const article = await roger.kb.create({
  title: "How refunds work",
  content: refundsMarkdown,
  status: "published",
  is_public: true,
  category: "billing",
});
```


Markdown body.
`draft` | `published` | `archived`.
Whether the article is reachable on the public hosted docs site.
Free-form category for grouping.

Published articles are indexed in the vector store for AI agent retrieval.

## Search

```bash
curl 'https://api.rogeriq.com/api/v1/projects/prj_xxx/kb/search?q=refund%20policy' \
  -H "X-API-Key: riq_xxx"
```

Hybrid search: vector similarity + BM25 keyword. Returns the top 10
articles ranked by combined score.

```json
{
  "data": [
    { "id": "kba_xxx", "title": "How refunds work", "score": 0.87, "...": "..." }
  ]
}
```

## Publish a draft

```bash
curl -X POST https://api.rogeriq.com/api/v1/projects/prj_xxx/kb/articles/kba_xxx/publish \
  -H "X-API-Key: riq_xxx"
```

Sets status to `published`, populates `published_at` (if unset), and
re-indexes the article in the vector store.

## Update

```bash
curl -X PATCH https://api.rogeriq.com/api/v1/projects/prj_xxx/kb/articles/kba_xxx \
  -H "X-API-Key: riq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated body...", "status": "published"}'
```

Editing a published article's title or content triggers re-vectorization
automatically.

## Delete

```bash
curl -X DELETE https://api.rogeriq.com/api/v1/projects/prj_xxx/kb/articles/kba_xxx \
  -H "X-API-Key: riq_xxx"
```

Removes the article and its vector entries.

## Crawl ingestion

For bulk import from an existing docs site, use the internal crawl
endpoint:

```bash
rogeriq kb crawl https://docs.example.com
```

Crawl progress is exposed via `GET /api/projects/:pid/kb/crawl` and is
currently dashboard-only — not stable v1 surface.