Edithly API — Developer guide

Edithly's REST API lets you create a chat session, upload a document to it, chat with that document (streaming or non-streaming), pull chat history, and run a full AI analysis — all over plain HTTP. It's the same document intelligence behind the Edithly app, callable from any language or backend.

Live, interactive reference: app.edithly.com/docs.

Base URL

https://api.edithly.com/api/v1

Before you connect

API key — create one from the dashboard → API Portal tab, the same key used for MCP. Watch: how to create an API key.
Auth header — send it as a bearer token on every request:

Authorization: Bearer YOUR_API_KEY

Quick start

Create a chatbox (session) — POST /external/chatbox/create. This is your workspace; save the session_id it returns.
Upload a document — POST /external/chatbox/{chatbox_id}/upload. PDF, DOCX, TXT, and more — up to 5MB.
Chat with it — POST /external/chat/create for a streaming (SSE) response, or POST /external/chat/create/sync for the complete response in one JSON payload.
Review history — GET /external/chat/{chatbox_id}/history any time.

Analyze Document

GET /external/analyze/{chatbox_id} returns a full AI analysis in one call — executive summary, key topics, sentiment, entities, insights, and token usage — as structured JSON. Worth calling right after upload if you just need the highlights, not a conversation.

All endpoints

Method	Endpoint	Path	What it does
POST	Create Chatbox	`/external/chatbox/create`	Start a new session
GET	List Chatboxes	`/external/chatbox/list`	List your sessions
POST	Upload File to Chatbox	`/external/chatbox/{chatbox_id}/upload`	Attach a document to a session
POST	Chat — Streaming	`/external/chat/create`	Chat, response streamed via SSE
POST	Chat — Sync	`/external/chat/create/sync`	Chat, complete response in one payload
GET	Get Chat History	`/external/chat/{chatbox_id}/history`	Retrieve past messages
GET	Analyze Document	`/external/analyze/{chatbox_id}`	Full structured AI analysis

Every request needs Authorization: Bearer YOUR_API_KEY. Endpoints that take a JSON body also need Content-Type: application/json.

Endpoint reference

Create Chatbox

Creates a new chatbox (session). Chatbox and session are interchangeable terms — the docs use both.

POST /external/chatbox/create

Request body

{
  "session_name": "My Research Session"
}

Response 200 OK

{
  "message": "Chatbox created successfully",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_name": "My Research Session",
  "created_at": "2026-03-07T10:30:00Z"
}

Save session_id — every other endpoint addresses this chatbox by it (as chatbox_id).

List Chatboxes

Returns all chatboxes belonging to the authenticated user.

GET /external/chatbox/list

Response 200 OK

{
  "chatboxes": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "My Research Session",
      "description": "",
      "created_at": "2026-03-07T08:00:00Z",
      "updated_at": "2026-03-07T10:30:00Z",
      "chunk_count": 145
    }
  ]
}

Upload File to Chatbox

Uploads and processes a document for a specific chatbox. Supported formats: PDF, DOCX, TXT, MD. Max file size: 5MB.

POST /external/chatbox/{chatbox_id}/upload

Request body — multipart/form-data with a file field. Don't set Content-Type manually; let your HTTP client set the multipart boundary.

Response 200 OK

{
  "message": "File uploaded and processed successfully",
  "file_name": "research_paper.pdf"
}

Chat — Streaming (SSE)

Sends a message and streams the AI response as Server-Sent Events.

POST /external/chat/create

Headers — Content-Type: application/json, Accept: text/event-stream

Request body

{
  "chatbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "What are the main findings in this document?"
}

Response — a stream of data: lines, one JSON object per line:

data: {"type":"start","chat_id":"abc-123","user_message":"Summarize this document"}

data: {"type":"content","content":"This document "}

data: {"type":"content","content":"covers the key findings..."}

data: {"type":"references","references":[{"text":"Relevant excerpt...","score":0.89}]}

data: {"type":"complete","full_response":"This document covers the key findings..."}

Event `type`	Meaning
`start`	Chat turn initiated
`content`	One token/chunk of the response
`references`	Source excerpts the answer drew from
`complete`	Full assembled response

Chat — Sync (Non-Streaming)

Same as streaming, but waits and returns the complete response as a single JSON object. Simpler for testing and server-side use where you don't need token-by-token output.

POST /external/chat/create/sync

Request body — identical to the streaming endpoint:

{
  "chatbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "What are the main findings in this document?"
}

Response 200 OK

{
  "chat_id": "chat-uuid-here",
  "user_message": "What are the main findings?",
  "response": "The main findings include...",
  "references": []
}

Get Chat History

Retrieves all previous messages for a chatbox session.

GET /external/chat/{chatbox_id}/history?limit=50

limit (query, optional) — maximum number of messages to return.

Response 200 OK

{
  "chatbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "chatbox_name": "My Research Session",
  "messages": [
    {
      "id": "msg_001",
      "message": "What is this document about?",
      "timestamp": "2026-03-07T10:00:00Z",
      "response": "This document discusses..."
    }
  ],
  "total_messages": 1
}

Analyze Document

Runs a full AI analysis on the uploaded document: executive summary, key topics, sentiment, entities, insights, and token usage.

GET /external/analyze/{chatbox_id}

Response 200 OK

{
  "message": "Analysis completed successfully",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "analysis_result": {
    "summary": "This document outlines a robust API structure for chatbot interactions with modern async Python patterns.",
    "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
  }
}

cURL walkthrough

API_KEY="YOUR_API_KEY"
BASE="https://api.edithly.com/api/v1"

# 1. Create a chatbox
SESSION_ID=$(curl -s -X POST "$BASE/external/chatbox/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_name": "My Research Session"}' | jq -r .session_id)

# 2. Upload a document
curl -s -X POST "$BASE/external/chatbox/$SESSION_ID/upload" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@research_paper.pdf"

# 3. Chat with it (sync)
curl -s -X POST "$BASE/external/chat/create/sync" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"chatbox_id\": \"$SESSION_ID\", \"message\": \"What are the main findings?\"}"

# 4. Run a full analysis
curl -s "$BASE/external/analyze/$SESSION_ID" \
  -H "Authorization: Bearer $API_KEY"

Postman collection

Prefer clicking through requests instead of writing code? Import the ready-made collection — it ships with the base_url and api_key variables pre-wired, and a test script that saves session_id into chatbox_id automatically after Create Chatbox runs.

Download the Postman collection

Quick reference

Endpoint	Purpose
`POST /external/chatbox/create`	Create a session
`GET /external/chatbox/list`	List your sessions
`POST /external/chatbox/{chatbox_id}/upload`	Upload a document (≤5MB)
`POST /external/chat/create`	Chat, streamed (SSE)
`POST /external/chat/create/sync`	Chat, complete response
`GET /external/chat/{chatbox_id}/history`	Chat history
`GET /external/analyze/{chatbox_id}`	Full document analysis

Troubleshooting

Problem	What to try
`401` / auth errors	Check the `Bearer` prefix and that the key hasn't been regenerated since
Upload rejected	Confirm the file is ≤5MB and one of PDF, DOCX, TXT, MD
Chat returns no references	Ingestion may still be running — wait for upload processing to finish before chatting
Streaming endpoint hangs in some clients	Some HTTP clients buffer SSE by default — try `/external/chat/create/sync` instead, or confirm your client streams response bodies

Still stuck? Mail [email protected], open Contact support, or ask in Join our Discord.

Before you connect​

Quick start​

All endpoints​

Endpoint reference​

Create Chatbox​

List Chatboxes​

Upload File to Chatbox​

Chat — Streaming (SSE)​

Chat — Sync (Non-Streaming)​

Get Chat History​

Analyze Document​

cURL walkthrough​

Postman collection​

Quick reference​

Troubleshooting​

Before you connect

Quick start

All endpoints

Endpoint reference

Create Chatbox

List Chatboxes

Upload File to Chatbox

Chat — Streaming (SSE)

Chat — Sync (Non-Streaming)

Get Chat History

Analyze Document

cURL walkthrough

Postman collection

Quick reference

Troubleshooting