Python SDK

Complete Python SDK for Archivus API.

Installation 

pip install archivus-python

Quick Start 

from archivus import ArchivusClient

# Initialize client
client = ArchivusClient(
    api_key="YOUR_API_KEY",
    tenant="your-tenant"
)

# List documents
documents = client.documents.list(limit=10)

# Upload document
document = client.documents.upload(
    "contract.pdf",
    folder_id="folder_xyz",
    enable_ai=True
)

# Search documents
results = client.search.search(
    query="contracts expiring soon",
    mode="semantic"
)

# Chat with document
session = client.chat.create_session(document.id, "Analysis")
response = client.chat.ask(session.id, "What are the key terms?")
print(response.content)

Client Initialization

API Key Authentication 

from archivus import ArchivusClient

client = ArchivusClient(
    api_key="ak_live_YOUR_API_KEY",
    tenant="your-tenant"
)

JWT Token Authentication 

from archivus import ArchivusClient

client = ArchivusClient(
    jwt_token="YOUR_JWT_TOKEN",
    tenant="your-tenant"
)

Documents

List Documents 

# Basic list
documents = client.documents.list()

# With filters
documents = client.documents.list(
    folder_id="folder_xyz",
    tag_id="tag_legal",
    limit=20,
    page=1
)

Get Document 

document = client.documents.get("doc_abc123")

Upload Document 

# Single upload
document = client.documents.upload(
    "contract.pdf",
    folder_id="folder_xyz",
    enable_ai=True,
    tags=["contract", "legal"]
)

# Batch upload
results = client.documents.upload_batch(
    ["doc1.pdf", "doc2.pdf", "doc3.pdf"],
    folder_id="folder_xyz"
)

Update Document 

document = client.documents.update(
    "doc_abc123",
    filename="Updated Name.pdf",
    tags=["updated", "important"]
)

Delete Document 

client.documents.delete("doc_abc123")

Download Document 

file_content = client.documents.download("doc_abc123")
with open("downloaded.pdf", "wb") as f:
    f.write(file_content)

# Semantic search
results = client.search.search(
    query="contracts expiring soon",
    mode="semantic",
    limit=20
)

# Keyword search
results = client.search.search(
    query="contract",
    mode="text"
)

results = client.search.enhanced_search(
    query="Find all contracts expiring in Q4",
    filters={
        "tags": ["contract"],
        "date_range": {
            "start": "2025-10-01",
            "end": "2025-12-31"
        }
    },
    min_score=0.7
)

results = client.search.hybrid_search(
    query="contract renewal",
    semantic_weight=0.7,
    text_weight=0.3
)

Chat

Create Session 

# Single document
session = client.chat.create_session(
    document_id="doc_abc123",
    name="Contract Analysis"
)

# Multiple documents
session = client.chat.create_session(
    document_ids=["doc_abc123", "doc_def456"],
    name="Multi-Doc Analysis"
)

Ask Question 

response = client.chat.ask(
    session.id,
    "What are the key terms of this contract?"
)

print(response.content)
print(f"Confidence: {response.confidence}")
print(f"Sources: {response.sources}")

RAG Query 

response = client.chat.ask_rag(
    session.id,
    "Find all contracts expiring in Q4 2025"
)

Get History 

history = client.chat.get_history(session.id, limit=50)
for message in history.messages:
    print(f"{message.role}: {message.content}")

Folders

List Folders 

folders = client.folders.list()

Create Folder 

folder = client.folders.create(
    name="Contracts",
    parent_id=None,
    color="#3B82F6",
    icon="folder"
)

Update Folder 

folder = client.folders.update(
    "folder_abc123",
    name="Updated Name",
    color="#EF4444"
)

Delete Folder 

client.folders.delete("folder_abc123", force=True)

Workspaces

Create Workspace 

workspace = client.workspaces.create(
    name="Legal Team",
    description="Legal documents and contracts"
)

Add Member 

client.workspaces.add_member(
    workspace.id,
    user_id="user_xyz789",
    role="member",
    permission="edit"
)

List Members 

members = client.workspaces.list_members(workspace.id)

Error Handling 

from archivus import ArchivusError, RateLimitError

try:
    document = client.documents.get("doc_abc123")
except ArchivusError as e:
    if e.code == "NOT_FOUND":
        print("Document not found")
    elif e.code == "RATE_LIMIT_EXCEEDED":
        print(f"Rate limit exceeded. Reset at: {e.reset_at}")
    else:
        print(f"Error: {e.message}")

Rate Limiting

The SDK automatically handles rate limits:

# SDK automatically waits when rate limited
documents = client.documents.list()  # May wait if rate limited

You can also check rate limit status:

# Check remaining requests
remaining = client.rate_limit.remaining
limit = client.rate_limit.limit
reset_at = client.rate_limit.reset_at

if remaining < 10:
    print(f"Approaching rate limit. Reset at: {reset_at}")

Advanced Usage

Custom Headers 

client = ArchivusClient(
    api_key="YOUR_API_KEY",
    tenant="your-tenant",
    headers={
        "X-Custom-Header": "value"
    }
)

Retry Configuration 

client = ArchivusClient(
    api_key="YOUR_API_KEY",
    tenant="your-tenant",
    max_retries=3,
    retry_delay=1.0
)

Async Support 

import asyncio
from archivus.async_client import AsyncArchivusClient

async def main():
    client = AsyncArchivusClient(
        api_key="YOUR_API_KEY",
        tenant="your-tenant"
    )
    
    documents = await client.documents.list()
    print(documents)

asyncio.run(main())

Complete Example 

from archivus import ArchivusClient

def main():
    # Initialize client
    client = ArchivusClient(
        api_key="YOUR_API_KEY",
        tenant="your-tenant"
    )
    
    # Upload document
    print("Uploading document...")
    document = client.documents.upload(
        "contract.pdf",
        folder_id="folder_legal",
        enable_ai=True
    )
    
    # Wait for processing
    print("Waiting for processing...")
    document = client.documents.wait_for_processing(document.id)
    
    # Search for similar documents
    print("Searching for similar documents...")
    results = client.search.search(
        query="contracts similar to this one",
        mode="semantic"
    )
    
    # Chat with document
    print("Analyzing document...")
    session = client.chat.create_session(document.id, "Analysis")
    response = client.chat.ask(
        session.id,
        "What are the key terms and risks?"
    )
    
    print(f"\nAnalysis: {response.content}")
    print(f"Confidence: {response.confidence:.2f}")

if __name__ == "__main__":
    main()

API Reference

Documents

  • list(**filters) - List documents
  • get(id) - Get document
  • upload(file_path, **options) - Upload document
  • upload_batch(file_paths, **options) - Batch upload
  • update(id, **updates) - Update document
  • delete(id) - Delete document
  • download(id) - Download document
  • wait_for_processing(id, timeout=300) - Wait for processing

Search

  • search(query, **options) - Basic search
  • enhanced_search(query, filters=None) - Enhanced search
  • hybrid_search(query, **options) - Hybrid search

Chat

  • create_session(document_ids, name=None) - Create session
  • ask(session_id, message) - Ask question
  • ask_rag(session_id, message) - RAG query
  • get_history(session_id, limit=50) - Get history
  • delete_session(session_id) - Delete session

Folders

  • list(**filters) - List folders
  • get(id) - Get folder
  • create(name, **options) - Create folder
  • update(id, **updates) - Update folder
  • delete(id, force=False) - Delete folder

Workspaces

  • list() - List workspaces
  • get(id) - Get workspace
  • create(name, **options) - Create workspace
  • add_member(workspace_id, user_id, **options) - Add member
  • list_members(workspace_id) - List members
  • remove_member(workspace_id, user_id) - Remove member

Next Steps

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