Skip to content

Developers

Build powerful applications with the Archivus API and SDKs.

Quick Start

Get started with the Archivus API in minutes:

# Login to get a token
curl -X POST https://api.archivus.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password",
    "tenant_subdomain": "your-tenant"
  }'

# Use the token to list documents
curl https://api.archivus.app/api/v1/documents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant"

import { ArchivusClient } from '@archivus/sdk';

const client = new ArchivusClient({
  apiKey: 'ak_live_YOUR_API_KEY',
  tenant: 'your-tenant'
});

// List documents
const documents = await client.documents.list({
  limit: 10
});

console.log(documents);

from archivus import ArchivusClient

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

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

package main

import (
    "github.com/archivus/archivus-go"
)

func main() {
    client := archivus.NewClient(
        "ak_live_YOUR_API_KEY",
        "your-tenant",
    )

    // List documents
    docs, err := client.Documents.List(context.Background(), &archivus.ListOptions{
        Limit: 10,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(docs)
}

Core Concepts

Authentication

Archivus supports two authentication methods:

  • API Keys - Recommended for server-to-server integrations (never expire)
  • JWT Tokens - For web and mobile applications (expire after 24 hours)

Learn more about authentication →

Base URLs

Production: https://api.archivus.app/api/v1
Development: http://localhost:8080/api/v1

Rate Limits

Rate limits vary by subscription tier:

Tier Rate Limit
Free 15 requests/minute
Starter 30 requests/minute
Pro 120 requests/minute
Team 300 requests/minute
Enterprise Unlimited

API Categories

Core APIs

Foundational document and search operations:

  • Documents API - Upload, manage, and download documents
  • Search API - Semantic and keyword search across documents
  • Chat API - AI-powered document Q&A with verification

Advanced Features

Enterprise-grade automation and integration:

Error Handling

SDKs

Official SDKs for popular languages:

  • JavaScript/TypeScript

    Full-featured SDK with TypeScript support

    JavaScript SDK

  • Python

    Pythonic interface with async support

    Python SDK

  • Go

    Idiomatic Go client with context support

    Go SDK

Code Examples

Practical examples for common use cases:

Upload and Process Document

const fs = require('fs');
const { ArchivusClient } = require('@archivus/sdk');

const client = new ArchivusClient({
  apiKey: process.env.ARCHIVUS_API_KEY,
  tenant: process.env.ARCHIVUS_TENANT
});

async function uploadDocument() {
  const file = fs.createReadStream('contract.pdf');

  const document = await client.documents.upload({
    file,
    folderId: 'folder_legal',
    enableAI: true
  });

  console.log('Document uploaded:', document.id);

  // Wait for AI processing
  while (document.ai_status !== 'completed') {
    await new Promise(resolve => setTimeout(resolve, 2000));
    document = await client.documents.get(document.id);
  }

  console.log('AI Summary:', document.ai_summary);
  console.log('AI Tags:', document.ai_tags);
}

uploadDocument();

import time
from archivus import ArchivusClient

client = ArchivusClient(
    api_key=os.environ['ARCHIVUS_API_KEY'],
    tenant=os.environ['ARCHIVUS_TENANT']
)

def upload_document():
    with open('contract.pdf', 'rb') as file:
        document = client.documents.upload(
            file=file,
            folder_id='folder_legal',
            enable_ai=True
        )

    print(f'Document uploaded: {document.id}')

    # Wait for AI processing
    while document.ai_status != 'completed':
        time.sleep(2)
        document = client.documents.get(document.id)

    print(f'AI Summary: {document.ai_summary}')
    print(f'AI Tags: {document.ai_tags}')

upload_document()

More examples →

const results = await client.search.query({
  q: 'contracts expiring in Q4 2025',
  mode: 'semantic',
  limit: 10
});

results.forEach(result => {
  console.log(`${result.document.filename} (score: ${result.score})`);
});

results = client.search.query(
    q='contracts expiring in Q4 2025',
    mode='semantic',
    limit=10
)

for result in results:
    print(f"{result.document.filename} (score: {result.score})")

Chat with Documents

// Create a chat session
const session = await client.chat.createSession({
  documentId: 'doc_abc123',
  name: 'Contract Analysis'
});

// Ask questions
const answer = await client.chat.ask(session.id, {
  message: 'What are the key terms and conditions?'
});

console.log(answer.content);
console.log('Confidence:', answer.confidence);
console.log('Sources:', answer.sources);

# Create a chat session
session = client.chat.create_session(
    document_id='doc_abc123',
    name='Contract Analysis'
)

# Ask questions
answer = client.chat.ask(
    session.id,
    message='What are the key terms and conditions?'
)

print(answer.content)
print(f'Confidence: {answer.confidence}')
print(f'Sources: {answer.sources}')

Best Practices

Security

API Key Security

Never commit API keys to version control. Use environment variables or secure secret management.

// ✅ Good - Use environment variables
const apiKey = process.env.ARCHIVUS_API_KEY;

// ❌ Bad - Hardcoded API key
const apiKey = 'ak_live_abc123...';

Error Handling

Always implement proper error handling:

try {
  const document = await client.documents.get('doc_abc123');
} catch (error) {
  if (error.code === 'NOT_FOUND') {
    console.error('Document not found');
  } else if (error.code === 'RATE_LIMIT_EXCEEDED') {
    // Wait and retry
    await sleep(error.details.reset_at);
  } else {
    console.error('Unexpected error:', error);
  }
}

Performance

  • Use pagination for list operations
  • Implement caching for frequently accessed data
  • Batch operations when possible
  • Monitor rate limits in response headers
// Check rate limit headers
const response = await client.documents.list();
console.log('Rate Limit:', response.headers['x-ratelimit-limit']);
console.log('Remaining:', response.headers['x-ratelimit-remaining']);

Support

Getting Help

Contributing

We welcome contributions! See our Contributing Guide.

Next Steps

  • Authenticate

    Get your API key and learn about authentication methods

    Authentication

  • Upload Documents

    Learn how to upload and manage documents via API

    Documents API

  • Search Documents

    Implement semantic search in your application

    Search API

  • AI Chat

    Build conversational interfaces for your documents

    Chat API