gitea/docs/phase5-ai-wiki-spec.md

Phase 5: AI-Friendly Wiki API (v2)

Version: 2.0 Date: January 2026 Status: IN PROGRESS

---

Overview

Phase 5 adds a v2 Wiki API designed for AI/LLM consumption and external plugin integration. This enhances the existing wiki functionality without modifying v1 endpoints.

Goals

1. AI-Ready Data - Structured responses optimized for LLM consumption
2. Full CRUD - Complete wiki management via API
3. Search - Full-text search across wiki content
4. Relationships - Page link graph for navigation
5. Health Metrics - Wiki statistics and maintenance insights
6. Plugin-Friendly - Enable external tools (like .NET AI plugins) to build on top

---

V2 API Endpoints

Base URL: /api/v2/repos/{owner}/{repo}/wiki

Pages CRUD

List All Pages

GET /api/v2/repos/{owner}/{repo}/wiki/pages

Query Parameters:

• include_content (bool, default: false) - Include full page content
• page (int) - Page number for pagination
• limit (int, default: 30) - Items per page

Response:

{
  "pages": [
    {
      "name": "Home",
      "title": "Home",
      "path": "Home.md",
      "url": "/owner/repo/wiki/Home",
      "word_count": 450,
      "last_commit": {
        "sha": "abc123",
        "author": "username",
        "message": "Updated home page",
        "date": "2026-01-08T10:00:00Z"
      },
      "content": "# Home\n\nWelcome...",  // if include_content=true
      "content_html": "<h1>Home</h1>..."     // if include_content=true
    }
  ],
  "total_count": 25,
  "has_more": false
}

Get Single Page

GET /api/v2/repos/{owner}/{repo}/wiki/pages/{pageName}

Response:

{
  "name": "Installation",
  "title": "Installation Guide",
  "path": "Installation.md",
  "url": "/owner/repo/wiki/Installation",
  "content": "# Installation\n\n...",
  "content_html": "<h1>Installation</h1>...",
  "word_count": 1250,
  "links_out": ["Home", "Configuration", "API-Reference"],
  "links_in": ["Home", "Getting-Started"],
  "sidebar": "...",
  "footer": "...",
  "last_commit": {
    "sha": "def456",
    "author": "username",
    "message": "Added troubleshooting section",
    "date": "2026-01-07T15:30:00Z"
  },
  "history_url": "/api/v2/repos/owner/repo/wiki/pages/Installation/revisions"
}

Create Page

POST /api/v2/repos/{owner}/{repo}/wiki/pages

Request:

{
  "name": "New-Page",
  "title": "New Page Title",
  "content": "# New Page\n\nContent here...",
  "message": "Created new page"
}

Response: Same as Get Single Page

Update Page

PUT /api/v2/repos/{owner}/{repo}/wiki/pages/{pageName}

Request:

{
  "title": "Updated Title",
  "content": "# Updated Content\n\n...",
  "message": "Updated page content",
  "rename_to": "new-page-name"  // optional, to rename
}

Response: Same as Get Single Page

Delete Page

DELETE /api/v2/repos/{owner}/{repo}/wiki/pages/{pageName}

Request:

{
  "message": "Removed outdated page"
}

Response:

{
  "success": true
}

---

Search

Full-Text Search

GET /api/v2/repos/{owner}/{repo}/wiki/search?q={query}

Query Parameters:

• q (string, required) - Search query
• limit (int, default: 20) - Max results
• include_content (bool, default: false) - Include full content

Response:

{
  "query": "installation docker",
  "results": [
    {
      "name": "Docker-Setup",
      "title": "Docker Setup Guide",
      "snippet": "...to run the <mark>installation</mark> in <mark>Docker</mark>, use the following...",
      "score": 0.95,
      "word_count": 800,
      "last_updated": "2026-01-05T12:00:00Z"
    }
  ],
  "total_count": 3
}

---

Link Graph

Get Page Relationships

GET /api/v2/repos/{owner}/{repo}/wiki/graph

Response:

{
  "nodes": [
    {"name": "Home", "word_count": 450},
    {"name": "Installation", "word_count": 1250},
    {"name": "Configuration", "word_count": 2100}
  ],
  "edges": [
    {"source": "Home", "target": "Installation"},
    {"source": "Home", "target": "Configuration"},
    {"source": "Installation", "target": "Configuration"}
  ]
}

---

Statistics & Health

Wiki Statistics

GET /api/v2/repos/{owner}/{repo}/wiki/stats

Response:

{
  "total_pages": 25,
  "total_words": 45000,
  "total_commits": 142,
  "last_updated": "2026-01-08T10:00:00Z",
  "contributors": 5,
  "health": {
    "orphaned_pages": [
      {"name": "Old-Notes", "word_count": 120}
    ],
    "dead_links": [
      {"page": "Home", "broken_link": "Deleted-Page"}
    ],
    "outdated_pages": [
      {"name": "Legacy-API", "last_edit": "2024-06-15T00:00:00Z", "days_old": 573}
    ],
    "short_pages": [
      {"name": "TODO", "word_count": 15}
    ]
  },
  "top_linked": [
    {"name": "Home", "incoming_links": 12},
    {"name": "Configuration", "incoming_links": 8}
  ]
}

---

Revisions

Get Page History

GET /api/v2/repos/{owner}/{repo}/wiki/pages/{pageName}/revisions

Query Parameters:

• page (int) - Page number
• limit (int, default: 30) - Items per page

Response:

{
  "page_name": "Installation",
  "revisions": [
    {
      "sha": "abc123",
      "author": {
        "username": "user1",
        "email": "user1@example.com",
        "avatar_url": "..."
      },
      "message": "Added troubleshooting section",
      "date": "2026-01-07T15:30:00Z",
      "additions": 45,
      "deletions": 12
    }
  ],
  "total_count": 28
}

---

Database Schema

wiki_index (for full-text search)

Column	Type	Description
id	BIGINT	Primary key
repo_id	BIGINT	Repository ID
page_name	VARCHAR(255)	Wiki page name
page_path	VARCHAR(512)	Git file path
title	VARCHAR(255)	Page title
content	LONGTEXT	Full page content (for search)
content_hash	VARCHAR(64)	SHA256 for change detection
commit_sha	VARCHAR(64)	Last indexed commit
word_count	INT	Word count
links_out	TEXT	JSON array of outgoing links
updated_unix	BIGINT	Last update timestamp
created_unix	BIGINT	Creation timestamp

Indexes: (repo_id), (repo_id, page_name) UNIQUE, FULLTEXT(title, content)

---

Implementation Plan

Files to Create

API Structs:

• modules/structs/repo_wiki_v2.go

API Router:

• routers/api/v2/repo/wiki.go

Services:

• services/wiki/wiki_index.go - Search indexing

Migration:

• models/migrations/v1_26/v328.go

Files to Modify

• routers/api/v2/api.go - Register wiki routes
• models/repo/wiki_ai.go - Simplify to just WikiIndex

---

V2 vs V1 Comparison

Feature	V1	V2
Content encoding	Base64	Plain JSON
HTML rendering	Separate call	Included in response
Word count	No	Yes
Link extraction	No	Yes
Search	No	Yes (full-text)
Graph	No	Yes
Statistics	No	Yes
Batch operations	No	Future

---

External Plugin Integration

Your .NET plugin can:

1. Fetch all wiki content via GET /wiki/pages?include_content=true
2. Generate AI summaries using your AI library
3. Create/update pages with AI-generated content
4. Build Q&A system by indexing content externally
5. Analyze relationships using the graph endpoint

The v2 API provides all the structured data needed for AI processing without building AI into Gitea itself.

---

End of Specification