API Reference¶

Complete REST API documentation for the Archivus platform.

Base URL¶

All API requests should be made to:

https://api.archivus.app/api/v1

For local development:

http://localhost:8080/api/v1

Authentication¶

Archivus supports two authentication methods:

API Key Authentication (Recommended)¶

For server-to-server integrations, use API key authentication:

curl -H "X-API-Key: ak_live_YOUR_API_KEY" \
     https://api.archivus.app/api/v1/documents

Benefits: - Never expires - Simpler integration - No token refresh needed - Ideal for backend services

Learn more about API keys →

JWT Token Authentication¶

For web and mobile applications:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "X-Tenant-Subdomain: your-tenant" \
     https://api.archivus.app/api/v1/documents

Benefits: - User-specific permissions - Secure for browser applications - OAuth integration support

Learn more about JWT tokens →

API Versioning¶

The current API version is v1, indicated in the URL path:

https://api.archivus.app/api/v1/...

We maintain backward compatibility within major versions. Breaking changes will result in a new version (v2, v3, etc.).

Response Format¶

Success Responses¶

Single resource responses return the object directly:

{
  "id": "doc_abc123",
  "filename": "contract.pdf",
  "status": "completed"
}

List responses include pagination metadata:

{
  "data": [
    { "id": "doc_1", "filename": "doc1.pdf" },
    { "id": "doc_2", "filename": "doc2.pdf" }
  ],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8
}

Error Responses¶

All errors follow a consistent format:

{
  "error": "not_found",
  "code": "NOT_FOUND",
  "message": "Document with ID 'abc123' not found",
  "details": {
    "resource_type": "document",
    "resource_id": "abc123"
  }
}

Complete error reference →

Rate Limits¶

Rate limits are enforced based on your subscription tier:

Rate Limit Headers¶

Every response includes rate limit information:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705392000

When rate limited, you'll receive a 429 Too Many Requests response:

{
  "error": "rate_limit_exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Please try again later.",
  "details": {
    "limit": 120,
    "remaining": 0,
    "reset_at": "2026-01-18T10:30:00Z"
  }
}

Pagination¶

List endpoints support pagination via query parameters:

Example:

curl "https://api.archivus.app/api/v1/documents?page=2&limit=50&sort=filename&order=asc" \
  -H "X-API-Key: YOUR_API_KEY"

Filtering¶

Many endpoints support filtering via query parameters:

# Filter documents by folder
curl "https://api.archivus.app/api/v1/documents?folder_id=folder_abc123"

# Filter by date range
curl "https://api.archivus.app/api/v1/documents?date_start=2026-01-01&date_end=2026-01-31"

# Combine filters
curl "https://api.archivus.app/api/v1/documents?folder_id=folder_abc123&file_type=pdf"

Idempotency¶

Mutation requests (POST, PUT, DELETE) support idempotency via the Idempotency-Key header:

curl -X POST https://api.archivus.app/api/v1/documents/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-12345" \
  -F "file=@document.pdf"

Duplicate requests with the same idempotency key will return the original response.

CORS¶

The API supports Cross-Origin Resource Sharing (CORS) for browser-based applications.

Allowed origins are configured per tenant in your dashboard settings.

API Endpoints¶

Core APIs¶

Advanced Features¶

Quick Examples¶

Upload a Document¶

curl -X POST https://api.archivus.app/api/v1/documents/upload \
  -H "X-API-Key: ak_live_YOUR_API_KEY" \
  -F "file=@contract.pdf" \
  -F "folder_id=folder_legal" \
  -F "enable_ai=true"

const fs = require('fs');
const FormData = require('form-data');

const form = new FormData();
form.append('file', fs.createReadStream('contract.pdf'));
form.append('folder_id', 'folder_legal');
form.append('enable_ai', 'true');

const response = await fetch('https://api.archivus.app/api/v1/documents/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': 'ak_live_YOUR_API_KEY',
    ...form.getHeaders()
  },
  body: form
});

const document = await response.json();

import requests

files = {'file': open('contract.pdf', 'rb')}
data = {
    'folder_id': 'folder_legal',
    'enable_ai': 'true'
}
headers = {'X-API-Key': 'ak_live_YOUR_API_KEY'}

response = requests.post(
    'https://api.archivus.app/api/v1/documents/upload',
    files=files,
    data=data,
    headers=headers
)

document = response.json()

Search Documents¶

curl "https://api.archivus.app/api/v1/search?q=contract+renewal&mode=semantic&limit=10" \
  -H "X-API-Key: ak_live_YOUR_API_KEY"

const params = new URLSearchParams({
  q: 'contract renewal',
  mode: 'semantic',
  limit: '10'
});

const response = await fetch(`https://api.archivus.app/api/v1/search?${params}`, {
  headers: { 'X-API-Key': 'ak_live_YOUR_API_KEY' }
});

const results = await response.json();

params = {
    'q': 'contract renewal',
    'mode': 'semantic',
    'limit': 10
}

response = requests.get(
    'https://api.archivus.app/api/v1/search',
    params=params,
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'}
)

results = response.json()

Chat with a Document¶

# Create session
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": "Analysis"}'

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

// Create session
const session = 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: 'Analysis'
  })
}).then(r => r.json());

// Ask question
const answer = await fetch(`https://api.archivus.app/api/v1/chat/sessions/${session.id}/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?'
  })
}).then(r => r.json());

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

# Ask question
answer = requests.post(
    f'https://api.archivus.app/api/v1/chat/sessions/{session["id"]}/ask',
    json={'message': 'What are the key terms?'},
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'}
).json()

Testing¶

Sandbox Environment¶

Test your integration in a sandbox environment:

https://sandbox.archivus.app/api/v1

Sandbox limitations: - Limited to 100 documents - AI processing may be slower - Data is cleared every 7 days - Rate limits are lower

Test API Keys¶

Use test API keys in sandbox:

ak_test_YOUR_TEST_KEY

Test keys are prefixed with ak_test_ and only work in the sandbox environment.

SDKs¶

Official SDKs for popular languages:

• JavaScript/TypeScript SDK
• Python SDK
• Go SDK

Support¶

Need help? We're here for you:

• Documentation: Browse these guides
• API Support: support@ubiship.com
• GitHub Issues: Report bugs
• Community: Join Discord

Next Steps¶