Chat API Endpoints

DeepWikiOpen provides powerful chat capabilities with streaming responses, deep research mode, conversation management, and real-time WebSocket connections.

Authentication

All chat endpoints require authentication using Bearer tokens:

Authorization: Bearer <your-api-key>

Rate Limits

Standard Chat: 100 requests per minute
Research Mode: 20 requests per minute
WebSocket: 1000 messages per minute
History Operations: 200 requests per minute

POST /chat/stream

Stream chat responses with RAG (Retrieval-Augmented Generation) capabilities.

message

string

required

The user’s message or question

conversation_id

string

Unique identifier for conversation continuity. Auto-generated if not provided.

model

string

default:"gpt-4-turbo"

AI model to use for response generationOptions: gpt-4-turbo, gpt-3.5-turbo, claude-3-opus, claude-3-sonnet

temperature

number

default:"0.7"

Response creativity (0.0 to 2.0)

max_tokens

number

default:"2048"

Maximum response length (1 to 4096)

context_sources

array

Specific knowledge sources to queryOptions: wikipedia, academic_papers, news, documentation, all

stream_options

object

Streaming configuration options

include_sources

boolean

default:"true"

Include source citations in stream

include_metadata

boolean

default:"false"

Include processing metadata

Request Example

curl -X POST "https://api.deepwikiopen.com/chat/stream" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explain quantum computing and its applications",
    "conversation_id": "conv_123",
    "model": "gpt-4-turbo",
    "temperature": 0.7,
    "context_sources": ["wikipedia", "academic_papers"],
    "stream_options": {
      "include_sources": true,
      "include_metadata": true
    }
  }'

Streaming Response Format (SSE)

The response is streamed using Server-Sent Events (SSE) format:

type

string

Type of stream chunkValues: start, content, sources, metadata, end, error

content

string

Text content (for content type chunks)

sources

array

Retrieved knowledge sources (for sources type chunks)

title

string

Source document title

url

string

Source URL or identifier

snippet

string

Relevant text excerpt

relevance_score

number

Relevance score (0.0 to 1.0)

metadata

object

Processing metadata (for metadata type chunks)

tokens_used

number

Total tokens consumed

processing_time

number

Processing time in milliseconds

sources_queried

number

Number of sources searched

Example Stream Response

data: {"type": "start", "conversation_id": "conv_123", "timestamp": "2024-01-15T10:30:00Z"}

data: {"type": "content", "content": "Quantum computing is a revolutionary"}

data: {"type": "content", "content": " approach to computation that leverages"}

data: {"type": "sources", "sources": [
  {
    "title": "Quantum Computing - Wikipedia",
    "url": "https://en.wikipedia.org/wiki/Quantum_computing",
    "snippet": "Quantum computing is a type of computation whose operations can harness the phenomena of quantum mechanics...",
    "relevance_score": 0.92
  }
]}

data: {"type": "content", "content": " quantum mechanical phenomena..."}

data: {"type": "metadata", "metadata": {"tokens_used": 156, "processing_time": 1250, "sources_queried": 5}}

data: {"type": "end", "conversation_id": "conv_123", "total_tokens": 156}

POST /chat/research

Trigger deep research mode for comprehensive, multi-source analysis.

query

string

required

Research question or topic

research_depth

string

default:"standard"

Depth of research analysisOptions: quick, standard, deep, comprehensive

source_types

array

Types of sources to include in researchOptions: academic, wikipedia, news, documentation, books, patents

time_range

object

Filter sources by publication date

start_date

string

Start date (ISO 8601 format)

end_date

string

End date (ISO 8601 format)

max_sources

number

default:"20"

Maximum number of sources to analyze (5 to 100)

output_format

string

default:"structured"

Response format structureOptions: structured, narrative, bullet_points, academic

Request Example

curl -X POST "https://api.deepwikiopen.com/chat/research" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Latest developments in CRISPR gene editing 2024",
    "research_depth": "deep",
    "source_types": ["academic", "news", "patents"],
    "time_range": {
      "start_date": "2024-01-01",
      "end_date": "2024-12-31"
    },
    "max_sources": 50,
    "output_format": "structured"
  }'

Response Format

research_id

string

Unique identifier for the research session

query

string

Original research query

summary

string

Executive summary of findings

key_findings

array

Main discoveries and insights

finding

string

Key insight or discovery

confidence

number

Confidence score (0.0 to 1.0)

supporting_sources

array

Sources supporting this finding

detailed_analysis

string

Comprehensive analysis text

sources

array

All sources analyzed

title

string

Source title

authors

array

Author names

publication_date

string

Publication date

url

string

Source URL

relevance_score

number

Relevance to query (0.0 to 1.0)

key_points

array

Important points from source

research_metadata

object

Research session metadata

sources_analyzed

number

Total sources processed

processing_time

number

Time taken in seconds

confidence_score

number

Overall confidence in findings

GET /chat/history

Retrieve conversation history for a specific conversation or user.

conversation_id

string

Specific conversation ID to retrieve

user_id

string

User ID to get all conversations for

limit

number

default:"50"

Maximum number of messages to return (1 to 1000)

offset

number

default:"0"

Number of messages to skip for pagination

start_date

string

Filter messages after this date (ISO 8601)

end_date

string

Filter messages before this date (ISO 8601)

Request Example

curl -X GET "https://api.deepwikiopen.com/chat/history?conversation_id=conv_123&limit=100" \
  -H "Authorization: Bearer your-api-key"

Response Format

conversation_id

string

Conversation identifier

messages

array

Array of conversation messages

string

Unique message identifier

role

string

Message sender roleValues: user, assistant, system

content

string

Message content

timestamp

string

Message timestamp (ISO 8601)

metadata

object

Additional message data

model_used

string

AI model that generated response

tokens_used

number

Tokens consumed for this message

sources

array

Knowledge sources used

pagination

object

Pagination information

total_messages

number

Total messages in conversation

has_more

boolean

Whether more messages are available

next_offset

number

Offset for next page

DELETE /chat/history

Clear conversation history for a specific conversation or user.

conversation_id

string

Specific conversation to clear (optional if user_id provided)

user_id

string

Clear all conversations for user (optional if conversation_id provided)

before_date

string

Only clear messages before this date (ISO 8601)

Request Example

curl -X DELETE "https://api.deepwikiopen.com/chat/history" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_123"
  }'

Response Format

success

boolean

Whether the operation was successful

messages_deleted

number

Number of messages deleted

conversations_affected

number

Number of conversations affected

WebSocket /ws/chat

Real-time bidirectional chat connection with live streaming and collaborative features.

Connection URL

wss://api.deepwikiopen.com/ws/chat?token=your-api-key&conversation_id=conv_123

Query Parameters

token

string

required

Your API authentication token

conversation_id

string

Conversation ID to connect to (auto-generated if not provided)

user_id

string

User identifier for multi-user conversations

Connection Example

const ws = new WebSocket('wss://api.deepwikiopen.com/ws/chat?token=your-api-key&conversation_id=conv_123');

ws.onopen = function(event) {
  console.log('Connected to chat WebSocket');
  
  // Send initial message
  ws.send(JSON.stringify({
    type: 'message',
    content: 'Hello, can you help me with quantum computing?',
    model: 'gpt-4-turbo'
  }));
};

ws.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
  
  switch(data.type) {
    case 'content':
      // Stream AI response content
      process.stdout.write(data.content);
      break;
    case 'user_message':
      // Another user's message in group chat
      console.log(`${data.user}: ${data.content}`);
      break;
    case 'typing':
      // Typing indicator
      console.log(`${data.user} is typing...`);
      break;
  }
};

ws.onerror = function(error) {
  console.error('WebSocket error:', error);
};

ws.onclose = function(event) {
  console.log('Disconnected from chat WebSocket');
};

Message Types

Client to Server Messages

type

string

required

Message typeValues: message, typing, stop_generation, join_room, leave_room

content

string

Message content (for message type)

model

string

AI model to use (for message type)

room_id

string

Room to join/leave (for room operations)

Server to Client Messages

type

string

Response typeValues: content, sources, user_message, typing, error, connection_info

content

string

Response content or user message

user

string

Username for user messages and typing indicators

conversation_id

string

Current conversation identifier

error

object

Error information (for error type)

code

string

Error code

message

string

Error description

Real-time Features

Typing Indicators

// Send typing indicator
ws.send(JSON.stringify({
  type: 'typing',
  is_typing: true
}));

// Stop typing indicator
ws.send(JSON.stringify({
  type: 'typing',
  is_typing: false
}));

Multi-user Chat Rooms

// Join a chat room
ws.send(JSON.stringify({
  type: 'join_room',
  room_id: 'quantum_physics_discussion'
}));

// Leave a chat room
ws.send(JSON.stringify({
  type: 'leave_room',
  room_id: 'quantum_physics_discussion'
}));

Stop AI Generation

// Stop the AI from generating more content
ws.send(JSON.stringify({
  type: 'stop_generation'
}));

Error Handling

HTTP Error Codes

400

Bad Request

Invalid request parameters or malformed JSON

401

Unauthorized

Missing or invalid API key

403

Forbidden

Insufficient permissions or quota exceeded

404

Not Found

Conversation or resource not found

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error - try again later

Error Response Format

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "details": {
      "retry_after": 60,
      "current_usage": 100,
      "limit": 100
    }
  }
}

WebSocket Error Codes

4000

Invalid Token

Authentication token is invalid or expired

4001

Rate Limited

Too many messages sent too quickly

4002

Invalid Message

Message format is invalid or unsupported

4003

Conversation Not Found

Specified conversation ID doesn’t exist

Real Conversation Examples

Basic Q&A with Streaming

# Request
curl -X POST "https://api.deepwikiopen.com/chat/stream" \
  -H "Authorization: Bearer demo-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What causes climate change?",
    "context_sources": ["wikipedia", "academic_papers"]
  }'

# Streaming Response
data: {"type": "start", "conversation_id": "conv_abc123"}

data: {"type": "content", "content": "Climate change is primarily caused by human activities that increase"}

data: {"type": "content", "content": " greenhouse gas concentrations in the atmosphere. The main causes include:"}

data: {"type": "sources", "sources": [
  {
    "title": "Climate Change - IPCC Report 2023",
    "url": "https://www.ipcc.ch/report/ar6/",
    "snippet": "Human influence has unequivocally warmed the planet...",
    "relevance_score": 0.95
  }
]}

data: {"type": "content", "content": "\n\n**1. Fossil Fuel Combustion**\nBurning coal, oil, and natural gas..."}

data: {"type": "end", "conversation_id": "conv_abc123", "total_tokens": 342}

Deep Research Mode

# Research Request
curl -X POST "https://api.deepwikiopen.com/chat/research" \
  -H "Authorization: Bearer demo-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Impact of AI on healthcare diagnostics",
    "research_depth": "comprehensive",
    "source_types": ["academic", "news", "documentation"],
    "max_sources": 25
  }'

# Response (truncated for brevity)
{
  "research_id": "research_xyz789",
  "query": "Impact of AI on healthcare diagnostics",
  "summary": "AI is revolutionizing healthcare diagnostics through machine learning algorithms that can analyze medical images, predict disease outcomes, and assist in early detection with unprecedented accuracy...",
  "key_findings": [
    {
      "finding": "AI diagnostic systems show 94% accuracy in detecting skin cancer vs 86% for dermatologists",
      "confidence": 0.92,
      "supporting_sources": ["Nature Medicine 2024", "JAMA Dermatology 2024"]
    }
  ],
  "sources": [
    {
      "title": "AI in Medical Diagnosis: A Systematic Review",
      "authors": ["Smith, J.", "Chen, L.", "Kumar, R."],
      "publication_date": "2024-03-15",
      "url": "https://doi.org/10.1038/s41591-024-2847-2",
      "relevance_score": 0.96,
      "key_points": [
        "Machine learning models outperform traditional diagnostic methods",
        "Reduced diagnostic errors by 23% in clinical trials"
      ]
    }
  ]
}

WebSocket Multi-user Chat

// User A connects and sends message
const wsA = new WebSocket('wss://api.deepwikiopen.com/ws/chat?token=user-a-key&room_id=ai_discussion');

wsA.send(JSON.stringify({
  type: 'message',
  content: 'What are the latest developments in transformer models?'
}));

// User B receives the message and AI response
// Message from User A: {"type": "user_message", "user": "UserA", "content": "What are..."}
// AI starts responding: {"type": "content", "content": "The latest developments..."}

// User B sends a follow-up
const wsB = new WebSocket('wss://api.deepwikiopen.com/ws/chat?token=user-b-key&room_id=ai_discussion');

wsB.send(JSON.stringify({
  type: 'message',
  content: 'Can you elaborate on attention mechanisms?'
}));

SDK Libraries

For easier integration, use our official SDK libraries:

Python: pip install deepwikiopen
JavaScript/Node.js: npm install deepwikiopen-sdk
Go: go get github.com/deepwikiopen/go-sdk
Rust: cargo add deepwikiopen

Each SDK provides typed interfaces, automatic retry logic, streaming support, and WebSocket management.

API Documentation

​Chat API Endpoints

​Authentication

​Rate Limits

​POST /chat/stream

​Request Example

​Streaming Response Format (SSE)

​Example Stream Response

​POST /chat/research

​Request Example

​Response Format

​GET /chat/history

​Request Example

​Response Format

​DELETE /chat/history

​Request Example

​Response Format

​WebSocket /ws/chat

​Connection URL

​Query Parameters

​Connection Example

​Message Types

​Client to Server Messages

​Server to Client Messages

​Real-time Features

​Typing Indicators

​Multi-user Chat Rooms

​Stop AI Generation

​Error Handling

​HTTP Error Codes

​Error Response Format

​WebSocket Error Codes

​Real Conversation Examples

​Basic Q&A with Streaming

​Deep Research Mode

​WebSocket Multi-user Chat

​SDK Libraries

Chat API Endpoints

Authentication

Rate Limits

POST /chat/stream

Request Example

Streaming Response Format (SSE)

Example Stream Response

POST /chat/research

Request Example

Response Format

GET /chat/history

Request Example

Response Format

DELETE /chat/history

Request Example

Response Format

WebSocket /ws/chat

Connection URL

Query Parameters

Connection Example

Message Types

Client to Server Messages

Server to Client Messages

Real-time Features

Typing Indicators

Multi-user Chat Rooms

Stop AI Generation

Error Handling

HTTP Error Codes

Error Response Format

WebSocket Error Codes

Real Conversation Examples

Basic Q&A with Streaming

Deep Research Mode

WebSocket Multi-user Chat

SDK Libraries