Chat API¶

AI-powered document Q&A with verifiable sources and confidence scores.

Overview¶

The Chat API enables conversational interaction with documents using AI:

Verifiable Answers - Every response includes source citations
Confidence Scores - Know how confident the AI is in its answers
Multi-Document Sessions - Chat across multiple documents
RAG Queries - Search and answer across your entire collection (Pro+)

Create Chat Session¶

Create a new chat session with one or more documents.

POST /api/v1/chat/sessions

Request Body¶

Single Document:

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

Multiple Documents:

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

Example Request¶

cURLJavaScriptPython

curl -X POST https://api.archivus.app/api/v1/chat/sessions \
  -H "X-API-Key: ak_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "doc_abc123",
    "name": "Contract Analysis"
  }'

const response = await fetch('https://api.archivus.app/api/v1/chat/sessions', {
  method: 'POST',
  headers: {
    'X-API-Key': 'ak_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    document_id: 'doc_abc123',
    name: 'Contract Analysis'
  })
});

const session = await response.json();

response = requests.post(
    'https://api.archivus.app/api/v1/chat/sessions',
    json={
        'document_id': 'doc_abc123',
        'name': 'Contract Analysis'
    },
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'}
)

session = response.json()

Response¶

{
  "id": "session_xyz789",
  "name": "Contract Analysis",
  "document_id": "doc_abc123",
  "created_at": "2026-01-18T10:30:00Z"
}

Ask Question¶

Ask a question in a chat session.

POST /api/v1/chat/sessions/{session_id}/ask

Request Body¶

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

Example Request¶

cURLJavaScriptPython

curl -X POST https://api.archivus.app/api/v1/chat/sessions/session_xyz789/ask \
  -H "X-API-Key: ak_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are the key terms?"}'

const response = await fetch(
  'https://api.archivus.app/api/v1/chat/sessions/session_xyz789/ask',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'ak_live_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: 'What are the key terms?'
    })
  }
);

const answer = await response.json();

response = requests.post(
    'https://api.archivus.app/api/v1/chat/sessions/session_xyz789/ask',
    json={'message': 'What are the key terms?'},
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'}
)

answer = response.json()

Response¶

{
  "message_id": "msg_123",
  "role": "assistant",
  "content": "The key terms of this contract include:\n\n1. **Term Duration**: 24 months starting January 1, 2026\n2. **Payment Terms**: Net 30 days from invoice date\n3. **Termination**: Either party may terminate with 30 days written notice\n4. **Renewal**: Automatic renewal for successive 12-month terms\n\nThese terms are outlined in Section 3 of the agreement.",
  "confidence": 0.95,
  "sources": [
    {
      "document_id": "doc_abc123",
      "page": 3,
      "excerpt": "Term: 24 months starting January 1, 2026. Payment terms: Net 30 days.",
      "relevance_score": 0.98
    },
    {
      "document_id": "doc_abc123",
      "page": 5,
      "excerpt": "Either party may terminate this agreement with 30 days written notice.",
      "relevance_score": 0.92
    }
  ],
  "created_at": "2026-01-18T10:31:00Z"
}

RAG Query (Pro+)¶

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

POST /api/v1/chat/sessions/{session_id}/ask-rag

This endpoint searches your entire document collection before answering, not just the session documents.

Request Body¶

{
  "message": "Find all contracts expiring in Q4 2026 and summarize their renewal terms"
}

Response¶

{
  "message_id": "msg_456",
  "role": "assistant",
  "content": "I found 5 contracts expiring in Q4 2026:\n\n1. **Service Agreement** (expires Dec 31, 2026)...",
  "confidence": 0.92,
  "sources": [
    {
      "document_id": "doc_abc123",
      "filename": "service-agreement.pdf",
      "relevance_score": 0.95
    },
    {
      "document_id": "doc_def456",
      "filename": "vendor-contract.pdf",
      "relevance_score": 0.88
    }
  ],
  "documents_searched": 150,
  "created_at": "2026-01-18T10:32:00Z"
}

Get Message History¶

Get conversation history for a session.

GET /api/v1/chat/sessions/{session_id}/messages

Query Parameters¶

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

Response¶

{
  "messages": [
    {
      "id": "msg_123",
      "role": "user",
      "content": "What are the key terms?",
      "created_at": "2026-01-18T10:30:00Z"
    },
    {
      "id": "msg_124",
      "role": "assistant",
      "content": "The key terms include...",
      "confidence": 0.95,
      "sources": [...],
      "created_at": "2026-01-18T10: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)

Response¶

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

Delete Session¶

Delete a chat session and its message history.

DELETE /api/v1/chat/sessions/{session_id}

Understanding Responses¶

Confidence Scores¶

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

Score	Confidence	Interpretation
0.9 - 1.0	Very High	Highly confident, well-supported by sources
0.7 - 0.9	High	Confident, good source support
0.5 - 0.7	Moderate	Some uncertainty, verify important details
< 0.5	Low	Low confidence, may be incomplete

Source Citations¶

Every answer includes source citations with:

document_id: Source document
page: Page number where information was found
excerpt: Exact text supporting the answer
relevance_score: How relevant this source is (0.0-1.0)

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

AI Credits Cost¶

Operation	Credits
Chat message	1 credit
RAG query	2 credits

Cost savings:

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¶

Upload Documents

Upload documents to chat with

Documents API
Search First

Find relevant documents before creating chat sessions

Search API