# Knowledge Module - API Documentation

Complete REST API reference for the Knowledge Module endpoints.

## Table of Contents

1. [Authentication](#authentication)
2. [Entry Endpoints](#entry-endpoints)
3. [Search Endpoints](#search-endpoints)
4. [Tag Endpoints](#tag-endpoints)
5. [Import/Export Endpoints](#importexport-endpoints)
6. [Stats Endpoints](#stats-endpoints)
7. [Cache Endpoints](#cache-endpoints)
8. [Error Responses](#error-responses)

---

## Authentication

All Knowledge Module endpoints require authentication via Bearer token and workspace context.

### Headers

```http
Authorization: Bearer {session_token}
x-workspace-id: {workspace_uuid}
```

### Permission Levels

- **WORKSPACE_ANY**: Any workspace member (including GUEST)
- **WORKSPACE_MEMBER**: MEMBER role or higher
- **WORKSPACE_ADMIN**: ADMIN or OWNER role

---

## Entry Endpoints

### List Entries

Get a paginated list of knowledge entries.

```http
GET /api/knowledge/entries
```

**Query Parameters:**

| Parameter | Type    | Default | Description                                   |
| --------- | ------- | ------- | --------------------------------------------- |
| `page`    | integer | 1       | Page number                                   |
| `limit`   | integer | 20      | Results per page (max: 100)                   |
| `status`  | string  | -       | Filter by status (DRAFT, PUBLISHED, ARCHIVED) |

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/entries?page=1&limit=20&status=PUBLISHED' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "slug": "react-hooks-guide",
      "title": "React Hooks Guide",
      "content": "# React Hooks Guide\n\nComprehensive guide...",
      "contentHtml": "<h1>React Hooks Guide</h1><p>Comprehensive guide...</p>",
      "summary": "Learn about React Hooks",
      "status": "PUBLISHED",
      "visibility": "WORKSPACE",
      "createdAt": "2024-01-29T10:00:00Z",
      "updatedAt": "2024-01-30T15:30:00Z",
      "createdBy": "user-uuid",
      "updatedBy": "user-uuid",
      "tags": [
        {
          "id": "tag-uuid",
          "name": "React",
          "slug": "react",
          "color": "#61dafb"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}
```

---

### Get Entry

Retrieve a single knowledge entry by slug.

```http
GET /api/knowledge/entries/:slug
```

**Path Parameters:**

| Parameter | Type   | Description                            |
| --------- | ------ | -------------------------------------- |
| `slug`    | string | Entry slug (e.g., "react-hooks-guide") |

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/entries/react-hooks-guide' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "react-hooks-guide",
  "title": "React Hooks Guide",
  "content": "# React Hooks Guide\n\nUse [[useState]] and [[useEffect]]...",
  "contentHtml": "<h1>React Hooks Guide</h1><p>Use <a>useState</a>...</p>",
  "summary": "Learn about React Hooks",
  "status": "PUBLISHED",
  "visibility": "WORKSPACE",
  "createdAt": "2024-01-29T10:00:00Z",
  "updatedAt": "2024-01-30T15:30:00Z",
  "createdBy": "user-uuid",
  "updatedBy": "user-uuid",
  "tags": [
    {
      "id": "tag-uuid",
      "name": "React",
      "slug": "react",
      "color": "#61dafb"
    }
  ]
}
```

---

### Create Entry

Create a new knowledge entry.

```http
POST /api/knowledge/entries
```

**Permissions:** WORKSPACE_MEMBER

**Request Body:**

```json
{
  "title": "React Hooks Guide",
  "content": "# React Hooks Guide\n\nContent here...",
  "summary": "Learn about React Hooks",
  "status": "DRAFT",
  "visibility": "WORKSPACE",
  "tags": ["react", "frontend"],
  "changeNote": "Initial draft"
}
```

**Body Schema:**

| Field        | Type     | Required | Constraints                                   |
| ------------ | -------- | -------- | --------------------------------------------- |
| `title`      | string   | Yes      | 1-500 characters                              |
| `content`    | string   | Yes      | Min 1 character                               |
| `summary`    | string   | No       | Max 1000 characters                           |
| `status`     | enum     | No       | DRAFT, PUBLISHED, ARCHIVED (default: DRAFT)   |
| `visibility` | enum     | No       | PRIVATE, WORKSPACE, PUBLIC (default: PRIVATE) |
| `tags`       | string[] | No       | Array of tag slugs                            |
| `changeNote` | string   | No       | Max 500 characters                            |

**Example Request:**

```bash
curl -X POST 'http://localhost:3001/api/knowledge/entries' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "React Hooks Guide",
    "content": "# React Hooks Guide\n\nUse [[useState]] for state...",
    "summary": "Learn about React Hooks",
    "status": "DRAFT",
    "tags": ["react", "frontend"],
    "changeNote": "Initial draft"
  }'
```

**Response:**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "react-hooks-guide",
  "title": "React Hooks Guide",
  "content": "# React Hooks Guide\n\nUse [[useState]] for state...",
  "contentHtml": "<h1>React Hooks Guide</h1><p>Use <a>useState</a>...</p>",
  "summary": "Learn about React Hooks",
  "status": "DRAFT",
  "visibility": "WORKSPACE",
  "createdAt": "2024-01-30T10:00:00Z",
  "updatedAt": "2024-01-30T10:00:00Z",
  "createdBy": "user-uuid",
  "updatedBy": "user-uuid",
  "tags": [
    {
      "id": "tag-uuid",
      "name": "React",
      "slug": "react",
      "color": "#61dafb"
    }
  ]
}
```

**Notes:**

- Slug is auto-generated from title
- If tags don't exist, they are created automatically
- Wiki-links in content are automatically parsed and stored
- First version (version 1) is created automatically

---

### Update Entry

Update an existing knowledge entry.

```http
PUT /api/knowledge/entries/:slug
```

**Path Parameters:**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `slug`    | string | Entry slug  |

**Permissions:** WORKSPACE_MEMBER

**Request Body:**

```json
{
  "title": "React Hooks Guide (Updated)",
  "content": "# React Hooks Guide\n\nUpdated content...",
  "summary": "Updated summary",
  "status": "PUBLISHED",
  "visibility": "WORKSPACE",
  "tags": ["react", "frontend", "tutorial"],
  "changeNote": "Added examples and updated title"
}
```

All fields are optional. Only provided fields are updated.

**Example Request:**

```bash
curl -X PUT 'http://localhost:3001/api/knowledge/entries/react-hooks-guide' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "PUBLISHED",
    "changeNote": "Ready for publication"
  }'
```

**Response:**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "react-hooks-guide",
  "title": "React Hooks Guide (Updated)",
  "content": "# React Hooks Guide\n\nUpdated content...",
  "contentHtml": "<h1>React Hooks Guide</h1><p>Updated...</p>",
  "summary": "Updated summary",
  "status": "PUBLISHED",
  "visibility": "WORKSPACE",
  "createdAt": "2024-01-30T10:00:00Z",
  "updatedAt": "2024-01-30T12:00:00Z",
  "createdBy": "user-uuid",
  "updatedBy": "user-uuid",
  "tags": [...]
}
```

**Notes:**

- A new version is created on every update
- Wiki-links are re-parsed and synchronized
- Cache is invalidated automatically

---

### Delete Entry

Soft-delete (archive) a knowledge entry.

```http
DELETE /api/knowledge/entries/:slug
```

**Path Parameters:**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `slug`    | string | Entry slug  |

**Permissions:** WORKSPACE_ADMIN

**Example Request:**

```bash
curl -X DELETE 'http://localhost:3001/api/knowledge/entries/react-hooks-guide' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "message": "Entry archived successfully"
}
```

**Notes:**

- This is a **soft delete** (sets status to ARCHIVED)
- Entry remains in database with all versions
- Links to this entry become unresolved
- Can be restored by updating status back to DRAFT or PUBLISHED

---

### Get Backlinks

Get all entries that link to this entry.

```http
GET /api/knowledge/entries/:slug/backlinks
```

**Path Parameters:**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `slug`    | string | Entry slug  |

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/entries/react-hooks/backlinks' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "entry": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "react-hooks",
    "title": "React Hooks"
  },
  "backlinks": [
    {
      "id": "link-uuid-1",
      "sourceId": "entry-uuid-1",
      "source": {
        "id": "entry-uuid-1",
        "slug": "frontend-guide",
        "title": "Frontend Development Guide",
        "summary": "Complete frontend guide"
      },
      "linkText": "React Hooks",
      "context": "Learn about [[React Hooks]] for state management.",
      "createdAt": "2024-01-29T10:00:00Z"
    },
    {
      "id": "link-uuid-2",
      "sourceId": "entry-uuid-2",
      "source": {
        "id": "entry-uuid-2",
        "slug": "component-patterns",
        "title": "React Component Patterns",
        "summary": null
      },
      "linkText": "hooks",
      "context": "Modern [[hooks|React hooks]] make state simple.",
      "createdAt": "2024-01-30T08:00:00Z"
    }
  ],
  "count": 2
}
```

**Notes:**

- Only resolved links are included
- Context shows surrounding text (future feature)
- Sorted by creation date (newest first)

---

### List Versions

Get version history for an entry.

```http
GET /api/knowledge/entries/:slug/versions
```

**Path Parameters:**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `slug`    | string | Entry slug  |

**Query Parameters:**

| Parameter | Type    | Default | Description                 |
| --------- | ------- | ------- | --------------------------- |
| `page`    | integer | 1       | Page number                 |
| `limit`   | integer | 20      | Results per page (max: 100) |

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/entries/react-hooks-guide/versions?page=1&limit=10' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "data": [
    {
      "id": "version-uuid-3",
      "version": 3,
      "title": "React Hooks Guide",
      "summary": "Learn about React Hooks",
      "changeNote": "Added examples",
      "createdAt": "2024-01-30T15:00:00Z",
      "createdBy": "user-uuid",
      "author": {
        "id": "user-uuid",
        "name": "John Doe",
        "email": "john@example.com"
      }
    },
    {
      "id": "version-uuid-2",
      "version": 2,
      "title": "React Hooks Guide",
      "summary": "Learn about React Hooks",
      "changeNote": "Fixed typos",
      "createdAt": "2024-01-30T12:00:00Z",
      "createdBy": "user-uuid",
      "author": { ... }
    },
    {
      "id": "version-uuid-1",
      "version": 1,
      "title": "React Hooks Guide",
      "summary": null,
      "changeNote": "Initial draft",
      "createdAt": "2024-01-30T10:00:00Z",
      "createdBy": "user-uuid",
      "author": { ... }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 3,
    "totalPages": 1
  }
}
```

**Notes:**

- Versions sorted newest first
- Content is NOT included (use Get Version endpoint for full content)
- First version has `changeNote` from creation

---

### Get Version

Get complete content for a specific version.

```http
GET /api/knowledge/entries/:slug/versions/:version
```

**Path Parameters:**

| Parameter | Type    | Description    |
| --------- | ------- | -------------- |
| `slug`    | string  | Entry slug     |
| `version` | integer | Version number |

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/entries/react-hooks-guide/versions/2' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "id": "version-uuid-2",
  "entryId": "entry-uuid",
  "version": 2,
  "title": "React Hooks Guide",
  "content": "# React Hooks Guide\n\nOld content...",
  "summary": "Learn about React Hooks",
  "changeNote": "Fixed typos",
  "createdAt": "2024-01-30T12:00:00Z",
  "createdBy": "user-uuid",
  "author": {
    "id": "user-uuid",
    "name": "John Doe",
    "email": "john@example.com"
  }
}
```

**Notes:**

- Includes full content as it existed in that version
- Use this to preview before restoring

---

### Restore Version

Restore an entry to a previous version.

```http
POST /api/knowledge/entries/:slug/restore/:version
```

**Path Parameters:**

| Parameter | Type    | Description               |
| --------- | ------- | ------------------------- |
| `slug`    | string  | Entry slug                |
| `version` | integer | Version number to restore |

**Permissions:** WORKSPACE_MEMBER

**Request Body:**

```json
{
  "changeNote": "Restored version 2 - reverted bad changes"
}
```

| Field        | Type   | Required | Constraints        |
| ------------ | ------ | -------- | ------------------ |
| `changeNote` | string | Yes      | Max 500 characters |

**Example Request:**

```bash
curl -X POST 'http://localhost:3001/api/knowledge/entries/react-hooks-guide/restore/2' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "changeNote": "Restored version 2 - reverted bad changes"
  }'
```

**Response:**

```json
{
  "id": "entry-uuid",
  "slug": "react-hooks-guide",
  "title": "React Hooks Guide",
  "content": "# React Hooks Guide\n\nRestored content...",
  "summary": "Learn about React Hooks",
  "status": "PUBLISHED",
  "visibility": "WORKSPACE",
  "createdAt": "2024-01-30T10:00:00Z",
  "updatedAt": "2024-01-30T16:00:00Z",
  "createdBy": "user-uuid",
  "updatedBy": "current-user-uuid",
  "tags": [...]
}
```

**Notes:**

- Creates a **new version** (e.g., version 4) with content from the specified version
- Original versions remain untouched (no history rewriting)
- Change note is required to document why you restored
- Wiki-links are re-parsed from the restored content

---

## Search Endpoints

### Full-Text Search

Search across entry titles and content.

```http
GET /api/knowledge/search
```

**Query Parameters:**

| Parameter | Type    | Required | Default | Description                 |
| --------- | ------- | -------- | ------- | --------------------------- |
| `q`       | string  | Yes      | -       | Search query                |
| `status`  | enum    | No       | -       | DRAFT, PUBLISHED, ARCHIVED  |
| `page`    | integer | No       | 1       | Page number                 |
| `limit`   | integer | No       | 20      | Results per page (max: 100) |

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/search?q=react+hooks&page=1&limit=10' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "data": [
    {
      "id": "entry-uuid",
      "slug": "react-hooks-guide",
      "title": "React Hooks Guide",
      "content": "# React Hooks Guide\n\nContent...",
      "summary": "Learn about React Hooks",
      "status": "PUBLISHED",
      "visibility": "WORKSPACE",
      "createdAt": "2024-01-30T10:00:00Z",
      "updatedAt": "2024-01-30T12:00:00Z",
      "createdBy": "user-uuid",
      "updatedBy": "user-uuid",
      "tags": [...]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "totalPages": 1
  }
}
```

**Search behavior:**

- Searches both `title` and `content` fields
- Case-insensitive
- Partial word matching
- Relevance-ranked results

---

### Search by Tags

Find entries with specific tags.

```http
GET /api/knowledge/search/by-tags
```

**Query Parameters:**

| Parameter | Type    | Required | Default | Description                 |
| --------- | ------- | -------- | ------- | --------------------------- |
| `tags`    | string  | Yes      | -       | Comma-separated tag slugs   |
| `status`  | enum    | No       | -       | DRAFT, PUBLISHED, ARCHIVED  |
| `page`    | integer | No       | 1       | Page number                 |
| `limit`   | integer | No       | 20      | Results per page (max: 100) |

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/search/by-tags?tags=react,frontend&status=PUBLISHED' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

Same format as Full-Text Search response.

**Notes:**

- Finds entries with **ALL** specified tags (AND logic)
- For OR logic, make separate requests

---

### Recent Entries

Get recently modified entries.

```http
GET /api/knowledge/search/recent
```

**Query Parameters:**

| Parameter | Type    | Default | Description                 |
| --------- | ------- | ------- | --------------------------- |
| `limit`   | integer | 10      | Number of entries (max: 50) |
| `status`  | enum    | -       | DRAFT, PUBLISHED, ARCHIVED  |

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/search/recent?limit=5&status=PUBLISHED' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "data": [
    {
      "id": "entry-uuid",
      "slug": "react-hooks-guide",
      "title": "React Hooks Guide",
      "summary": "Learn about React Hooks",
      "status": "PUBLISHED",
      "updatedAt": "2024-01-30T16:00:00Z",
      "tags": [...]
    }
  ],
  "count": 5
}
```

**Notes:**

- Sorted by `updatedAt` descending (newest first)
- Does not include full content (use Get Entry for details)

---

## Tag Endpoints

### List Tags

Get all tags in the workspace.

```http
GET /api/knowledge/tags
```

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/tags' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
[
  {
    "id": "tag-uuid-1",
    "name": "React",
    "slug": "react",
    "color": "#61dafb",
    "description": "React library and ecosystem"
  },
  {
    "id": "tag-uuid-2",
    "name": "Frontend",
    "slug": "frontend",
    "color": "#3b82f6",
    "description": null
  }
]
```

---

### Get Tag

Get a single tag by slug.

```http
GET /api/knowledge/tags/:slug
```

**Path Parameters:**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `slug`    | string | Tag slug    |

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/tags/react' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "id": "tag-uuid",
  "name": "React",
  "slug": "react",
  "color": "#61dafb",
  "description": "React library and ecosystem"
}
```

---

### Create Tag

Create a new tag.

```http
POST /api/knowledge/tags
```

**Permissions:** WORKSPACE_MEMBER

**Request Body:**

```json
{
  "name": "TypeScript",
  "color": "#3178c6",
  "description": "TypeScript language and tooling"
}
```

| Field         | Type   | Required | Constraints                 |
| ------------- | ------ | -------- | --------------------------- |
| `name`        | string | Yes      | Unique per workspace        |
| `color`       | string | No       | Hex color (e.g., "#3178c6") |
| `description` | string | No       | -                           |

**Example Request:**

```bash
curl -X POST 'http://localhost:3001/api/knowledge/tags' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TypeScript",
    "color": "#3178c6"
  }'
```

**Response:**

```json
{
  "id": "new-tag-uuid",
  "name": "TypeScript",
  "slug": "typescript",
  "color": "#3178c6",
  "description": null
}
```

**Notes:**

- Slug is auto-generated from name
- Tags are workspace-scoped (same slug can exist in different workspaces)

---

### Update Tag

Update an existing tag.

```http
PUT /api/knowledge/tags/:slug
```

**Path Parameters:**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `slug`    | string | Tag slug    |

**Permissions:** WORKSPACE_MEMBER

**Request Body:**

All fields are optional. Only provided fields are updated.

```json
{
  "name": "TypeScript (Updated)",
  "color": "#2f74c0",
  "description": "TypeScript programming language"
}
```

**Example Request:**

```bash
curl -X PUT 'http://localhost:3001/api/knowledge/tags/typescript' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "#2f74c0"
  }'
```

**Response:**

```json
{
  "id": "tag-uuid",
  "name": "TypeScript (Updated)",
  "slug": "typescript",
  "color": "#2f74c0",
  "description": "TypeScript programming language"
}
```

---

### Delete Tag

Delete a tag (removes from all entries).

```http
DELETE /api/knowledge/tags/:slug
```

**Path Parameters:**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `slug`    | string | Tag slug    |

**Permissions:** WORKSPACE_ADMIN

**Example Request:**

```bash
curl -X DELETE 'http://localhost:3001/api/knowledge/tags/typescript' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```
204 No Content
```

**Notes:**

- Tag is removed from all entries that used it
- Entries themselves are NOT deleted

---

### Get Tag Entries

Get all entries with a specific tag.

```http
GET /api/knowledge/tags/:slug/entries
```

**Path Parameters:**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `slug`    | string | Tag slug    |

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/tags/react/entries' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
[
  {
    "id": "entry-uuid-1",
    "slug": "react-hooks-guide",
    "title": "React Hooks Guide",
    "summary": "Learn about React Hooks",
    "status": "PUBLISHED",
    "createdAt": "2024-01-30T10:00:00Z",
    "updatedAt": "2024-01-30T12:00:00Z"
  },
  {
    "id": "entry-uuid-2",
    "slug": "component-patterns",
    "title": "React Component Patterns",
    "summary": null,
    "status": "PUBLISHED",
    "createdAt": "2024-01-29T08:00:00Z",
    "updatedAt": "2024-01-29T09:00:00Z"
  }
]
```

---

## Import/Export Endpoints

### Export Entries

Export knowledge entries as a downloadable archive.

```http
GET /api/knowledge/export
```

**Query Parameters:**

| Parameter  | Type     | Default  | Description                           |
| ---------- | -------- | -------- | ------------------------------------- |
| `format`   | enum     | markdown | Export format: `markdown` or `json`   |
| `entryIds` | string[] | -        | Optional array of entry IDs to export |

**Permissions:** WORKSPACE_ANY

**Example Requests:**

Export all entries as Markdown:

```bash
curl -X GET 'http://localhost:3001/api/knowledge/export?format=markdown' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -o knowledge-export.zip
```

Export specific entries as JSON:

```bash
curl -X GET 'http://localhost:3001/api/knowledge/export?format=json&entryIds[]=uuid1&entryIds[]=uuid2' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -o knowledge-export.zip
```

**Response:**

Binary `.zip` file with headers:

```
Content-Type: application/zip
Content-Disposition: attachment; filename="knowledge-export-YYYYMMDD-HHMMSS.zip"
```

**Markdown format structure:**

```
knowledge-export.zip
├── react-hooks-guide.md
├── component-patterns.md
└── state-management.md
```

Each `.md` file:

```markdown
---
slug: react-hooks-guide
title: React Hooks Guide
status: PUBLISHED
visibility: WORKSPACE
tags: react, frontend
createdAt: 2024-01-30T10:00:00Z
updatedAt: 2024-01-30T12:00:00Z
---

# React Hooks Guide

Content with [[wiki-links]]...
```

**JSON format structure:**

```
knowledge-export.zip
└── entries.json
```

`entries.json`:

```json
[
  {
    "slug": "react-hooks-guide",
    "title": "React Hooks Guide",
    "content": "# React Hooks Guide\n\nContent...",
    "summary": "Learn about React Hooks",
    "status": "PUBLISHED",
    "visibility": "WORKSPACE",
    "tags": ["react", "frontend"],
    "createdAt": "2024-01-30T10:00:00Z",
    "updatedAt": "2024-01-30T12:00:00Z"
  }
]
```

---

### Import Entries

Import knowledge entries from uploaded file.

```http
POST /api/knowledge/import
```

**Permissions:** WORKSPACE_MEMBER

**Request:**

Multipart form data with file upload.

```bash
curl -X POST 'http://localhost:3001/api/knowledge/import' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -F "file=@knowledge-export.zip"
```

**Supported file types:**

- `.md` (single Markdown file)
- `.zip` (archive of Markdown files)

**File size limit:** 50MB

**Response:**

```json
{
  "success": true,
  "totalFiles": 10,
  "imported": 8,
  "failed": 2,
  "results": [
    {
      "filename": "react-hooks.md",
      "success": true,
      "entryId": "new-entry-uuid",
      "slug": "react-hooks"
    },
    {
      "filename": "invalid-entry.md",
      "success": false,
      "error": "Title is required"
    }
  ]
}
```

**Import behavior:**

- New entries created with status DRAFT
- Existing entries (matching slug) are skipped
- Tags created automatically if they don't exist
- Wiki-links preserved (will resolve if targets exist)

**Front matter parsing:**

The importer reads YAML front matter:

```markdown
---
slug: custom-slug
title: Entry Title
summary: Optional summary
status: PUBLISHED
visibility: WORKSPACE
tags: tag1, tag2
---

Content starts here...
```

If no front matter, slug is generated from filename.

---

## Stats Endpoints

### Get Statistics

Get knowledge base statistics for the workspace.

```http
GET /api/knowledge/stats
```

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/stats' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "totalEntries": 42,
  "entriesByStatus": {
    "DRAFT": 5,
    "PUBLISHED": 35,
    "ARCHIVED": 2
  },
  "totalTags": 12,
  "totalLinks": 87,
  "totalVersions": 215,
  "averageVersionsPerEntry": 5.1,
  "topTags": [
    {
      "id": "tag-uuid",
      "name": "React",
      "slug": "react",
      "count": 15
    },
    {
      "id": "tag-uuid",
      "name": "Frontend",
      "slug": "frontend",
      "count": 12
    }
  ],
  "mostLinkedEntries": [
    {
      "id": "entry-uuid",
      "slug": "react-hooks",
      "title": "React Hooks",
      "incomingLinkCount": 8
    }
  ],
  "recentActivity": {
    "last24h": 5,
    "last7days": 18,
    "last30days": 42
  }
}
```

---

## Cache Endpoints

### Get Cache Stats

Get cache performance statistics.

```http
GET /api/knowledge/cache/stats
```

**Permissions:** WORKSPACE_ANY

**Example Request:**

```bash
curl -X GET 'http://localhost:3001/api/knowledge/cache/stats' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "enabled": true,
  "stats": {
    "hits": 1250,
    "misses": 180,
    "sets": 195,
    "deletes": 15,
    "hitRate": 0.874
  }
}
```

**Stats explanation:**

- `hits`: Cache hits (data found in cache)
- `misses`: Cache misses (data not in cache, fetched from DB)
- `sets`: Cache writes
- `deletes`: Cache invalidations
- `hitRate`: Percentage of requests served from cache (hits / (hits + misses))

---

### Clear Cache

Clear all cached data for the workspace.

```http
POST /api/knowledge/cache/clear
```

**Permissions:** WORKSPACE_ADMIN

**Example Request:**

```bash
curl -X POST 'http://localhost:3001/api/knowledge/cache/clear' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "message": "Cache cleared successfully"
}
```

**Notes:**

- Clears ALL knowledge caches for the workspace
- Includes entry caches, search caches, and graph caches
- Does not affect other workspaces

---

### Reset Cache Stats

Reset cache statistics counters to zero.

```http
POST /api/knowledge/cache/stats/reset
```

**Permissions:** WORKSPACE_ADMIN

**Example Request:**

```bash
curl -X POST 'http://localhost:3001/api/knowledge/cache/stats/reset' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: WORKSPACE_ID"
```

**Response:**

```json
{
  "message": "Cache statistics reset successfully"
}
```

---

## Error Responses

All endpoints follow standard HTTP error codes and return JSON error objects.

### Error Format

```json
{
  "statusCode": 404,
  "message": "Entry not found",
  "error": "Not Found"
}
```

### Common Status Codes

| Code  | Meaning               | Example                                      |
| ----- | --------------------- | -------------------------------------------- |
| `400` | Bad Request           | Invalid request body, missing required field |
| `401` | Unauthorized          | Missing or invalid auth token                |
| `403` | Forbidden             | Insufficient permissions for action          |
| `404` | Not Found             | Entry, tag, or version doesn't exist         |
| `409` | Conflict              | Slug already exists, duplicate entry         |
| `413` | Payload Too Large     | Import file exceeds 50MB limit               |
| `422` | Unprocessable Entity  | Validation failed (e.g., invalid enum value) |
| `500` | Internal Server Error | Unexpected server error                      |

### Validation Errors

When validation fails, you get detailed error information:

```json
{
  "statusCode": 422,
  "message": [
    "title must not be empty",
    "title must not exceed 500 characters",
    "status must be a valid EntryStatus"
  ],
  "error": "Unprocessable Entity"
}
```

---

## JavaScript Examples

### Using Fetch API

```javascript
const API_URL = "http://localhost:3001/api";
const token = "YOUR_SESSION_TOKEN";
const workspaceId = "YOUR_WORKSPACE_ID";

const headers = {
  Authorization: `Bearer ${token}`,
  "x-workspace-id": workspaceId,
  "Content-Type": "application/json",
};

// Create entry
async function createEntry() {
  const response = await fetch(`${API_URL}/knowledge/entries`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      title: "My New Entry",
      content: "# Hello World\n\nThis is my first [[wiki-link]]!",
      tags: ["tutorial"],
      status: "DRAFT",
    }),
  });

  if (!response.ok) {
    throw new Error(`Failed: ${response.status}`);
  }

  return await response.json();
}

// Search entries
async function searchEntries(query) {
  const params = new URLSearchParams({ q: query, limit: 10 });
  const response = await fetch(`${API_URL}/knowledge/search?${params}`, {
    headers,
  });

  return await response.json();
}

// Export entries
async function exportEntries() {
  const response = await fetch(`${API_URL}/knowledge/export?format=markdown`, {
    headers,
  });

  const blob = await response.blob();
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement("a");
  a.href = url;
  a.download = "knowledge-export.zip";
  a.click();
}
```

### Using Axios

```javascript
import axios from "axios";

const api = axios.create({
  baseURL: "http://localhost:3001/api",
  headers: {
    Authorization: `Bearer ${token}`,
    "x-workspace-id": workspaceId,
  },
});

// Get entry
const entry = await api.get("/knowledge/entries/react-hooks");
console.log(entry.data);

// Update entry
const updated = await api.put("/knowledge/entries/react-hooks", {
  status: "PUBLISHED",
  changeNote: "Ready for publication",
});

// Import file
const formData = new FormData();
formData.append("file", fileInput.files[0]);
const result = await api.post("/knowledge/import", formData, {
  headers: { "Content-Type": "multipart/form-data" },
});
```

---

## Next Steps

- **[User Guide](KNOWLEDGE_USER_GUIDE.md)** — Learn how to use the Knowledge Module
- **[Developer Guide](KNOWLEDGE_DEV.md)** — Architecture and implementation details
- **[Main README](README.md)** — Complete Mosaic Stack documentation

---

**Happy building! 🚀**
