API Overview - DeepWiki-Open

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.

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

Basic Wiki Generation

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": 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

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

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": {
    "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

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

WebSocket API

For real-time updates during wiki generation and chat:

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

API Documentation

​API Base URL

​API Architecture

Wiki Generation

Chat & RAG

Model Management

WebSocket API

​Quick Start

​Authentication

​Basic Wiki Generation

​Core Endpoints

​Wiki Generation

​Chat & RAG

​Model Configuration

​Data Models

​WikiPage

​RepoInfo

​Error Handling

​Common Error Codes

​Rate Limits

​Provider Rate Limits

​WebSocket API

​SDK Examples

​Python SDK Usage

​Node.js SDK Usage

​Next Steps

Wiki Endpoints

Chat API

WebSocket API

Authentication

API Base URL

API Architecture

Quick Start

Authentication

Basic Wiki Generation

Core Endpoints

Wiki Generation

Chat & RAG

Model Configuration

Data Models

WikiPage

RepoInfo

Error Handling

Common Error Codes

Rate Limits

Provider Rate Limits

WebSocket API

SDK Examples

Python SDK Usage

Node.js SDK Usage

Next Steps