API Overview

Complete guide to the DeepWiki-Open REST API for programmatic wiki generation and repository analysis

The DeepWiki-Open API provides programmatic access to all wiki generation and repository analysis features. Built with FastAPI, it offers high-performance endpoints for integration into your development workflows.

API Base URL

For production deployments, replace with your actual API server URL.

API Architecture

The DeepWiki API is organized into several key areas:

Wiki Generation

Generate comprehensive documentation wikis from repository URLs

Chat & RAG

Interactive Q&A with repository content using RAG

Model Management

Configure and manage AI model providers

WebSocket API

Real-time streaming for generation progress and chat

Quick Start

Authentication

Most endpoints require authentication via environment-configured API keys. The API validates your configured providers automatically.

Test API Health

curl -X GET "http://localhost:8001/health"

Basic Wiki Generation

cURL

curl -X POST "http://localhost:8001/wiki/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/microsoft/TypeScript-Node-Starter",
    "model_provider": "google",
    "model_name": "gemini-2.0-flash",
    "force_regenerate": false
  }'

Success Response

{
  "success": true,
  "wiki_id": "wiki_1234567890",
  "repo_info": {
    "url": "https://github.com/microsoft/TypeScript-Node-Starter",
    "name": "TypeScript-Node-Starter",
    "owner": "microsoft",
    "platform": "github"
  },
  "generation_status": "completed",
  "wiki_pages": [
    {
      "id": "overview",
      "title": "Project Overview", 
      "content": "TypeScript Node Starter is...",
      "importance": "high",
      "filePaths": ["README.md", "package.json"],
      "relatedPages": ["setup", "architecture"]
    }
  ],
  "metadata": {
    "generated_at": "2024-01-15T10:30:00Z",
    "model_used": "gemini-2.0-flash",
    "processing_time": 45.2,
    "total_files_analyzed": 127
  }
}

Core Endpoints

Wiki Generation

POST /wiki/generate

Generate a comprehensive wiki from a repository URL.

Request Body:

• repo_url (string, required): Repository URL
• model_provider (string): AI provider (google, openai, openrouter, azure, ollama)
• model_name (string): Specific model to use
• force_regenerate (boolean): Force regeneration even if cached
• access_token (string): Repository access token for private repos
• auth_code (string): Authorization code (if auth mode enabled)

Response: Complete wiki structure with pages and metadata

GET /wiki/projects

List all processed repositories and their wiki status.

Query Parameters:

• limit (integer): Number of results to return
• offset (integer): Pagination offset

Response: Array of processed projects with generation status

GET /wiki/{project_id}

Retrieve a specific generated wiki by project ID.

Path Parameters:

• project_id (string): Unique project identifier

Response: Complete wiki data including all pages

Chat & RAG

POST /chat/stream

Stream chat responses using RAG on repository content.

Request Body:

• message (string, required): User question
• repo_url (string, required): Repository URL for context
• conversation_history (array): Previous conversation messages
• model_provider (string): AI provider for responses
• deep_research (boolean): Enable multi-turn research mode

Response: Server-sent events with streaming chat responses

Model Configuration

GET /models/config

Get available model providers and configurations.

Response: Available providers, models, and their parameters

POST /models/validate

Validate API keys and model availability.

Request Body:

• provider (string): Provider to validate
• model_name (string): Specific model to test

Response: Validation status and model information

Data Models

WikiPage

id · string · required

Unique identifier for the wiki page

title · string · required

Human-readable page title

content · string · required

Full page content in Markdown format with Mermaid diagrams

filePaths · array · required

Source file paths that contributed to this page

importance · string · required

Page importance level: high, medium, or low

relatedPages · array

Array of related page IDs for cross-references

RepoInfo

url · string · required

Full repository URL

name · string · required

Repository name

owner · string · required

Repository owner/organization

platform · string · required

Git platform: github, gitlab, or bitbucket

private · boolean

Whether the repository is private

default_branch · string

Default branch name (usually main or master)

Error Handling

The API uses standard HTTP status codes and returns detailed error information:

Error Response

{
  "error": {
    "code": "INVALID_REPOSITORY",
    "message": "Repository not found or not accessible",
    "details": {
      "repo_url": "https://github.com/invalid/repo",
      "status_code": 404,
      "suggestion": "Verify the repository URL and access permissions"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Common Error Codes

400 Bad Request

Common causes:

• Invalid repository URL format
• Missing required parameters
• Invalid model provider/name combination

Example:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid repository URL format",
    "details": {
      "field": "repo_url",
      "provided": "not-a-valid-url",
      "expected": "https://github.com/owner/repo"
    }
  }
}

401 Unauthorized

Common causes:

• Missing or invalid API keys
• Repository access token required but not provided
• Invalid authorization code

Example:

{
  "error": {
    "code": "API_KEY_INVALID", 
    "message": "Google API key is invalid or expired",
    "details": {
      "provider": "google",
      "suggestion": "Check your GOOGLE_API_KEY environment variable"
    }
  }
}

404 Not Found

Common causes:

• Repository doesn’t exist
• Repository is private and requires access token
• Wiki not found for the given project ID

Example:

{
  "error": {
    "code": "REPOSITORY_NOT_FOUND",
    "message": "Repository not accessible",
    "details": {
      "repo_url": "https://github.com/private/repo",
      "suggestion": "Provide access_token for private repositories"
    }
  }
}

429 Too Many Requests

Common causes:

• API rate limits exceeded
• AI provider rate limits reached

Example:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "OpenAI API rate limit exceeded",
    "details": {
      "provider": "openai", 
      "retry_after": 60,
      "suggestion": "Wait 60 seconds before retrying or use a different provider"
    }
  }
}

500 Internal Server Error

Common causes:

• AI model generation failures
• Repository processing errors
• Configuration issues

Example:

{
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Wiki generation failed due to model error",
    "details": {
      "model": "gpt-4o",
      "stage": "content_generation",
      "suggestion": "Try a different model or contact support"
    }
  }
}

Rate Limits

Rate limits depend on your AI provider’s limits. DeepWiki doesn’t impose additional rate limits.

Provider Rate Limits

OpenAI

• GPT-4: 500 requests/minute, 30,000 tokens/minute
• GPT-3.5: 3,500 requests/minute, 90,000 tokens/minute
• Varies by usage tier and model

Google Gemini

• Free tier: 15 requests/minute, 32,000 tokens/minute
• Paid tier: 360 requests/minute, 120,000 tokens/minute

OpenRouter

• Varies by model and payment plan
• Some models have per-request costs
• Check OpenRouter pricing

Azure OpenAI

• Configurable limits per deployment
• Enterprise-grade quotas available
• Contact Microsoft for high-volume needs

WebSocket API

For real-time updates during wiki generation and chat:

WebSocket Connection

const ws = new WebSocket('ws://localhost:8001/ws/wiki/generate');

ws.onopen = () => {
  ws.send(JSON.stringify({
    repo_url: 'https://github.com/microsoft/vscode',
    model_provider: 'google',
    model_name: 'gemini-2.0-flash'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  switch(data.type) {
    case 'progress':
      console.log(`Progress: ${data.progress}%`);
      break;
    case 'page_generated':
      console.log(`Generated page: ${data.page.title}`);
      break;
    case 'completed':
      console.log('Wiki generation completed!');
      break;
    case 'error':
      console.error('Error:', data.error);
      break;
  }
};

SDK Examples

Python SDK Usage

import asyncio
import aiohttp
import json

class DeepWikiClient:
    def __init__(self, base_url="http://localhost:8001"):
        self.base_url = base_url
    
    async def generate_wiki(self, repo_url, model_provider="google", 
                          model_name="gemini-2.0-flash"):
        async with aiohttp.ClientSession() as session:
            payload = {
                "repo_url": repo_url,
                "model_provider": model_provider,
                "model_name": model_name
            }
            
            async with session.post(
                f"{self.base_url}/wiki/generate",
                json=payload
            ) as response:
                return await response.json()
    
    async def ask_question(self, question, repo_url):
        async with aiohttp.ClientSession() as session:
            payload = {
                "message": question,
                "repo_url": repo_url
            }
            
            async with session.post(
                f"{self.base_url}/chat/stream",
                json=payload
            ) as response:
                async for line in response.content:
                    yield json.loads(line.decode())

# Usage
async def main():
    client = DeepWikiClient()
    
    # Generate wiki
    wiki = await client.generate_wiki(
        "https://github.com/fastapi/fastapi"
    )
    print(f"Generated {len(wiki['wiki_pages'])} pages")
    
    # Ask questions
    async for response in client.ask_question(
        "How does FastAPI handle dependency injection?",
        "https://github.com/fastapi/fastapi"
    ):
        print(response['content'], end='', flush=True)

asyncio.run(main())

Node.js SDK Usage

class DeepWikiClient {
  constructor(baseUrl = 'http://localhost:8001') {
    this.baseUrl = baseUrl;
  }

  async generateWiki(repoUrl, options = {}) {
    const {
      modelProvider = 'google',
      modelName = 'gemini-2.0-flash',
      forceRegenerate = false
    } = options;

    const response = await fetch(`${this.baseUrl}/wiki/generate`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        repo_url: repoUrl,
        model_provider: modelProvider,
        model_name: modelName,
        force_regenerate: forceRegenerate
      })
    });

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

    return await response.json();
  }

  async *askQuestion(question, repoUrl) {
    const response = await fetch(`${this.baseUrl}/chat/stream`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        message: question,
        repo_url: repoUrl
      })
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value);
      const lines = chunk.split('\n').filter(line => line.trim());
      
      for (const line of lines) {
        if (line.startsWith('data: ')) {
          try {
            yield JSON.parse(line.slice(6));
          } catch (e) {
            console.warn('Failed to parse SSE data:', line);
          }
        }
      }
    }
  }
}

// Usage
const client = new DeepWikiClient();

async function example() {
  try {
    // Generate wiki
    const wiki = await client.generateWiki(
      'https://github.com/expressjs/express'
    );
    console.log(`Generated ${wiki.wiki_pages.length} pages`);

    // Ask question with streaming response
    console.log('\nAsking question...');
    for await (const chunk of client.askQuestion(
      'Explain Express.js middleware system',
      'https://github.com/expressjs/express'
    )) {
      if (chunk.type === 'content') {
        process.stdout.write(chunk.content);
      }
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
}

example();

Next Steps

Wiki Endpoints

Detailed wiki generation and management endpoints

Chat API

Interactive chat and RAG endpoints for repository Q&A

WebSocket API

Real-time streaming APIs for live updates

Authentication

API authentication and security configuration