Follow these simple steps to start using the Edithly API for document chat and analysis.
Before you can start chatting or analyzing documents, you need to create a chatbox (also called a session). This is your workspace where documents and conversations are stored.
Endpoint: POST /external/chatbox/create
Note: Chatbox and Session' are interchangeable terms - they both refer to the same thing.
To use the chat feature, you must first upload a document to your chatbox. The API will process and index this document for AI-powered conversations.
Endpoint: POST /external/chatbox/{chatbox_id}/upload
Supported formats: PDF, DOCX, TXT, and more
Once your document is uploaded, you can start asking questions! Choose between two response types:
Streaming Response (Recommended)
Get real-time, token-by-token responses as the AI generates them - perfect for interactive chat experiences.
POST /external/chat/createNon-Streaming Response
Get the complete response all at once - simpler but less interactive.
POST /external/chat/create/syncRetrieve all previous conversations from a specific chatbox to maintain context or review past interactions.
Endpoint: GET /external/chat/{chatbox_id}/history
Get a comprehensive AI-generated analysis of your document including summary, key topics, sentiment, entities, and insights - all returned as structured JSON data!
Endpoint: GET /external/analyze/{chatbox_id}
What you get:
{
"summary": "Comprehensive analysis...",
"key_topics": ["AI", "MCP", "API Design"],
"sentiment": "neutral",
"entities": ["FastAPI", "Python"],
"insights": [...],
"token_usage": {...}
}/external/chatbox/create{
"Content-Type": "application/json",
"Authorization": "Bearer <your-api-key>"
}{
"session_name": "My Research Session"
}{
"Content-Type": "application/json"
}{
"message": "Chatbox created successfully",
"session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"session_name": "My Research Session",
"created_at": "2026-02-09T10:30:00Z"
}/external/chatbox/list{
"Content-Type": "application/json",
"Authorization": "Bearer <your-api-key>"
}{
"Content-Type": "application/json"
}{
"chatboxes": [
{
"id": "507f1f77bcf86cd799439011",
"name": "Research Documents",
"description": "Analysis of research papers",
"created_at": "2026-02-01T08:00:00Z",
"updated_at": "2026-02-08T15:30:00Z",
"chunk_count": 145
},
{
"id": "507f1f77bcf86cd799439012",
"name": "Product Specifications",
"description": "Technical documentation review",
"created_at": "2026-02-05T10:15:00Z",
"updated_at": "2026-02-09T09:00:00Z",
"chunk_count": 89
}
]
}/external/chatbox/a1b2c3d4-e5f6-7890-abcd-ef1234567890/upload{
"Content-Type": "multipart/form-data",
"Authorization": "Bearer <your-api-key>"
}FormData with 'file' field containing the document (PDF, DOCX, TXT, etc.) Max file size: 5MB
{
"Content-Type": "application/json"
}{
"message": "File uploaded and processed successfully",
"file_name": "research_paper.pdf"
}/external/chat/create{
"Content-Type": "application/json",
"Authorization": "Bearer <your-api-key>"
}{
"chatbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "What are the main findings in this document?"
}{
"Content-Type": "text/event-stream",
"Cache-Control": "no-cache",
"Connection": "keep-alive"
}data: {"type":"start","chat_id":"chat_uuid_here","user_message":"What are the main findings?","res":[...]}
data: {"type":"content","content":"The main findings "}
data: {"type":"content","content":"from this document include..."}
data: {"type":"references","references":[{"text":"Relevant excerpt...","score":0.89}]}
data: {"type":"complete","full_response":"The main findings from this document include..."}/external/chat/a1b2c3d4-e5f6-7890-abcd-ef1234567890/history?limit=50{
"Content-Type": "application/json",
"Authorization": "Bearer <your-api-key>"
}{
"Content-Type": "application/json"
}{
"chatbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"chatbox_name": "My Research Session",
"messages": [
{
"id": "msg_001",
"message": "What is this document about?",
"timestamp": "2026-02-09T10:00:00Z",
"response": "This document discusses AI development trends and MCP protocols..."
},
{
"id": "msg_002",
"message": "Can you summarize the key points?",
"timestamp": "2026-02-09T10:05:00Z",
"response": "The key points include: 1) Evolution of AI systems, 2) MCP client-server architecture..."
}
],
"total_messages": 2
}/external/analyze/a1b2c3d4-e5f6-7890-abcd-ef1234567890{
"Content-Type": "application/json",
"Authorization": "Bearer <your-api-key>"
}{
"Content-Type": "application/json"
}{
"message": "Analysis completed successfully",
"session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"analysis_result": {
"summary": "Comprehensive analysis of the document content...",
"key_topics": [
"AI Development",
"MCP Architecture",
"API Design"
],
"sentiment": "neutral",
"entities": [
"FastAPI",
"Python",
"MongoDB",
"S3"
],
"insights": [
"The document outlines a robust API structure for chatbot interactions",
"Implementation uses modern async Python patterns",
"Integration with cloud storage and vector search capabilities"
]
},
"token_usage": {
"prompt_tokens": 2450,
"completion_tokens": 380,
"total_tokens": 2830
}
}/external/chat/create/sync{
"Content-Type": "application/json",
"Authorization": "Bearer <your-api-key>"
}{"chatbox_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","message":"What are the main findings in this document?"}{
"Content-Type": "text/event-stream",
"Cache-Control": "no-cache",
"Connection": "keep-alive"
}{"chat_id":"chat_uuid_here","user_message":"Hi","response":"Hello! How can I assist you today?","references":[]}