Chat API

Complete API reference for AI chat endpoints.

---

Create Chat Session

Create a new chat session with one or more documents.

POST /api/v1/chat/sessions

Request

Single Document:

{
  "document_id": "doc_abc123",
  "name": "Contract Analysis"
}

Multiple Documents:

{
  "document_ids": ["doc_abc123", "doc_def456"],
  "name": "Multi-Doc Analysis"
}

Example

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

Response

{
  "id": "session_xyz789",
  "name": "Contract Analysis",
  "document_id": "doc_abc123",
  "created_at": "2025-12-16T10:30:00Z"
}

---

Ask Question

Ask a question in a chat session.

POST /api/v1/chat/sessions/:id/ask

Request

{
  "message": "What are the key terms of this contract?"
}

Example

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

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

---

RAG Query (Pro+)

Search across all documents using RAG (Retrieval-Augmented Generation).

POST /api/v1/chat/sessions/:id/ask-rag

Request

{
  "message": "Find all contracts expiring in Q4 2025"
}

Example

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

Response

{
  "message_id": "msg_456",
  "role": "assistant",
  "content": "I found 5 contracts expiring in Q4 2025:\n\n1. Service Agreement (expires Dec 31, 2025)\n2. ...",
  "confidence": 0.92,
  "sources": [
    {
      "document_id": "doc_abc123",
      "relevance_score": 0.95
    }
  ],
  "created_at": "2025-12-16T10:32:00Z"
}

---

Get Message History

Get conversation history for a session.

GET /api/v1/chat/sessions/:id/messages

Query Parameters

Parameter	Type	Description
limit	integer	Max messages to return (default: 50)
before	string	Get messages before this message ID

Example

curl "https://api.archivus.app/api/v1/chat/sessions/session_xyz789/messages?limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant"

Response

{
  "messages": [
    {
      "id": "msg_123",
      "role": "user",
      "content": "What are the key terms?",
      "created_at": "2025-12-16T10:30:00Z"
    },
    {
      "id": "msg_124",
      "role": "assistant",
      "content": "The key terms include...",
      "confidence": 0.95,
      "sources": [...],
      "created_at": "2025-12-16T10:31:00Z"
    }
  ]
}

---

List Sessions

Get all chat sessions.

GET /api/v1/chat/sessions

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20)

Example

curl "https://api.archivus.app/api/v1/chat/sessions?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant"

Response

{
  "data": [
    {
      "id": "session_xyz789",
      "name": "Contract Analysis",
      "document_id": "doc_abc123",
      "message_count": 5,
      "created_at": "2025-12-16T10:30:00Z",
      "updated_at": "2025-12-16T10:35:00Z"
    }
  ],
  "total": 10,
  "page": 1,
  "page_size": 20
}

---

Delete Session

Delete a chat session and its history.

DELETE /api/v1/chat/sessions/:id

Example

curl -X DELETE https://api.archivus.app/api/v1/chat/sessions/session_xyz789 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN"

Response

{
  "message": "Chat session deleted successfully"
}

---

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

Sources

Responses include source citations:

{
  "sources": [
    {
      "document_id": "doc_abc123",
      "page": 3,
      "excerpt": "Term: 24 months starting January 1, 2025"
    }
  ]
}

“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": []
}

---

Code Examples

Python

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 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")
session = chat.create_session("doc_abc123", "Contract Analysis")
answer = chat.ask(session["id"], "What are the key terms?")
print(answer["content"])

JavaScript

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 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');
const session = await chat.createSession('doc_abc123', 'Contract Analysis');
const answer = await chat.ask(session.id, 'What are the key terms?');
console.log(answer.content);

---

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

---

Error Responses

Session Not Found

Status: 404 Not Found

{
  "error": "not_found",
  "code": "NOT_FOUND",
  "message": "Chat session not found"
}

Document Not Processed

Status: 400 Bad Request

{
  "error": "document_not_processed",
  "code": "DOCUMENT_NOT_PROCESSED",
  "message": "Document must be processed before creating chat session"
}

---

Next Steps

• Documents API - Upload documents to chat with
• Search API - Find documents to chat about
• Error Handling - Handle errors properly

---

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