Chat with Documents

Learn how to use Archie, Archivus’s AI assistant, to ask questions and get answers about your documents.

---

Overview

Archie is Archivus’s AI-powered chat assistant that understands your documents and can answer questions about them. It uses advanced AI to provide accurate answers with citations and confidence scores.

---

Quick Start

1. Create Chat Session

curl -X POST https://api.archivus.app/api/v1/chat/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "doc_abc123",
    "name": "Contract Analysis"
  }'

2. Ask a Question

curl -X POST https://api.archivus.app/api/v1/chat/sessions/session_xyz789/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the key terms of this contract?"
  }'

Response:

{
  "message_id": "msg_123",
  "role": "assistant",
  "content": "The key terms of this contract include:\n\n1. **Term Duration**: 24 months\n2. **Payment Terms**: Net 30 days\n3. **Termination**: 30 days notice\n\n...",
  "confidence": 0.95,
  "sources": [
    {
      "document_id": "doc_abc123",
      "page": 3,
      "excerpt": "Term: 24 months starting January 1, 2025"
    }
  ],
  "created_at": "2025-12-16T10:31:00Z"
}

---

Chat Features

Single Document Chat

Chat about one specific document:

curl -X POST https://api.archivus.app/api/v1/chat/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "doc_abc123",
    "name": "Contract Q&A"
  }'

Multi-Document Chat

Chat across multiple documents:

curl -X POST https://api.archivus.app/api/v1/chat/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": ["doc_abc123", "doc_def456", "doc_ghi789"],
    "name": "Multi-Doc Analysis"
  }'

RAG Chat (Pro+)

Search across all your documents:

curl -X POST https://api.archivus.app/api/v1/chat/sessions/session_xyz789/ask-rag \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Find all contracts expiring in Q4 2025"
  }'

---

Code Examples

Python - Chat Integration

import requests

class ArchivusChat:
    def __init__(self, api_key, tenant):
        self.api_key = api_key
        self.tenant = tenant
        self.base_url = "https://api.archivus.app/api/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "X-Tenant-Subdomain": tenant
        }
    
    def create_session(self, document_ids, name=None):
        url = f"{self.base_url}/chat/sessions"
        if isinstance(document_ids, str):
            data = {"document_id": document_ids}
        else:
            data = {"document_ids": document_ids}
        if name:
            data["name"] = name
        
        response = requests.post(url, headers=self.headers, json=data)
        return response.json()
    
    def ask(self, session_id, message):
        url = f"{self.base_url}/chat/sessions/{session_id}/ask"
        data = {"message": message}
        response = requests.post(url, headers=self.headers, json=data)
        return response.json()
    
    def ask_rag(self, session_id, message):
        url = f"{self.base_url}/chat/sessions/{session_id}/ask-rag"
        data = {"message": message}
        response = requests.post(url, headers=self.headers, json=data)
        return response.json()
    
    def get_history(self, session_id):
        url = f"{self.base_url}/chat/sessions/{session_id}/messages"
        response = requests.get(url, headers=self.headers)
        return response.json()

# Usage
chat = ArchivusChat("YOUR_API_KEY", "your-tenant")

# Create session
session = chat.create_session("doc_abc123", "Contract Analysis")

# Ask question
answer = chat.ask(session["id"], "What are the key terms?")
print(answer["content"])
print(f"Confidence: {answer['confidence']}")

# Follow-up question (Archie remembers context)
follow_up = chat.ask(session["id"], "Can it be extended?")
print(follow_up["content"])

# Get conversation history
history = chat.get_history(session["id"])

JavaScript - Chat Integration

class ArchivusChat {
  constructor(apiKey, tenant) {
    this.apiKey = apiKey;
    this.tenant = tenant;
    this.baseURL = 'https://api.archivus.app/api/v1';
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'X-Tenant-Subdomain': tenant
    };
  }
  
  async createSession(documentIds, name = null) {
    const data = Array.isArray(documentIds)
      ? { document_ids: documentIds }
      : { document_id: documentIds };
    if (name) data.name = name;
    
    const response = await fetch(`${this.baseURL}/chat/sessions`, {
      method: 'POST',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    return response.json();
  }
  
  async ask(sessionId, message) {
    const response = await fetch(`${this.baseURL}/chat/sessions/${sessionId}/ask`, {
      method: 'POST',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify({ message })
    });
    return response.json();
  }
  
  async askRAG(sessionId, message) {
    const response = await fetch(`${this.baseURL}/chat/sessions/${sessionId}/ask-rag`, {
      method: 'POST',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify({ message })
    });
    return response.json();
  }
  
  async getHistory(sessionId) {
    const response = await fetch(`${this.baseURL}/chat/sessions/${sessionId}/messages`, {
      headers: this.headers
    });
    return response.json();
  }
}

// Usage
const chat = new ArchivusChat('YOUR_API_KEY', 'your-tenant');

// Create session
const session = await chat.createSession('doc_abc123', 'Contract Analysis');

// Ask question
const answer = await chat.ask(session.id, 'What are the key terms?');
console.log(answer.content);
console.log('Confidence:', answer.confidence);

// Follow-up question
const followUp = await chat.ask(session.id, 'Can it be extended?');
console.log(followUp.content);

// Get history
const history = await chat.getHistory(session.id);

---

Understanding Responses

Confidence Score

Every response includes a confidence score (0.0 to 1.0):

• 0.9 - 1.0: High confidence - Very likely accurate
• 0.7 - 0.9: Good confidence - Likely accurate
• 0.5 - 0.7: Moderate confidence - Verify important details
• < 0.5: Low confidence - May be incomplete or uncertain

Sources

Responses include source citations:

{
  "sources": [
    {
      "document_id": "doc_abc123",
      "page": 3,
      "excerpt": "Term: 24 months starting January 1, 2025"
    },
    {
      "document_id": "doc_abc123",
      "page": 5,
      "excerpt": "Payment terms: Net 30 days"
    }
  ]
}

“Not in Document” Responses

If information isn’t in the document:

{
  "content": "I don't see information about that topic in the provided document.",
  "confidence": 0.0,
  "sources": []
}

---

Best Practices

Ask Specific Questions

Good:

• “What is the termination clause?”
• “Who are the parties to this contract?”
• “What are the payment terms?”
• “When does this contract expire?”

Less Effective:

• “Tell me everything about this document”
• “What does this say?”
• “Summarize this”

Use Follow-up Questions

Archie remembers conversation history:

# First question
answer1 = chat.ask(session_id, "What is the contract term?")

# Follow-up (Archie remembers context)
answer2 = chat.ask(session_id, "Can it be extended?")
answer3 = chat.ask(session_id, "What's the process?")

Check Confidence Scores

For important decisions:

• Review source citations
• Ask the question differently
• Check the original document
• Verify low-confidence answers

---

Advanced Features

Context Windowing

Archie automatically manages conversation context:

• Recent messages kept in full
• Older messages summarized
• Reduces costs by 60-80%
• Maintains conversation quality

Prompt Caching

Repeated content is cached:

• Same document context cached
• Reduces token usage by 70-90%
• Faster responses
• Lower costs

Multi-Document Analysis

Compare and analyze multiple documents:

# Create session with multiple documents
session = chat.create_session(
    ["doc_abc123", "doc_def456"],
    "Contract Comparison"
)

# Ask comparative questions
answer = chat.ask(
    session["id"],
    "What are the differences between these contracts?"
)

---

Cost

• Chat message: 1 AI credit
• RAG query: 2 AI credits
• Context windowing: Saves 60-80% on costs
• Prompt caching: Saves 70-90% on repeated content

---

Next Steps

• Semantic Search Guide - Find documents by meaning
• Document Analysis - Advanced AI analysis features
• API Reference - Complete chat API documentation

---

Questions? Check the FAQ or contact support@ubiship.com