API Reference

Complete API documentation for Archivus Document Intelligence Platform

Archivus provides a comprehensive REST API covering document management, AI features, search, collaboration, and enterprise features.

Quick Start

Base URLs 

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

Authentication

Archivus supports two authentication methods:

API Key Authentication (Recommended for integrations):

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

JWT Session Authentication (For browser apps):

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

See the Authentication guide for detailed information.

Response Formats

Success Responses

Data is returned directly at the root level (not wrapped in a data field):

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

Paginated Responses

List endpoints return structured pagination:

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

Error Responses

Consistent error format:

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

See the Errors guide for complete error handling information.

Quick Example 

# 1. Login
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"
  }'

# Response includes JWT token
{
  "token": "eyJhbGc...",
  "user": { ... },
  "tenant": { ... }
}

# 2. Use token for authenticated requests
curl -H "Authorization: Bearer eyJhbGc..." \
     -H "X-Tenant-Subdomain: your-tenant" \
     https://api.archivus.app/api/v1/documents

API Categories

Core Features

  • Authentication - Login, register, OAuth, API keys
  • Documents - Upload, manage, download, search
  • Folders - Organization and structure
  • Search - Full-text and semantic search
  • Chat - AI-powered document Q&A

Advanced Features

Endpoint Summary

Authentication (14 endpoints)

  • Login, register, logout
  • Password reset and email verification
  • OAuth (Google, Apple, GitHub)
  • API key management
  • CSRF token management

Documents (22 endpoints)

  • Upload (single and batch)
  • List, get, update, delete
  • Download, preview, thumbnail
  • Share and permissions
  • Search and filtering
  • Version management

Chat (18 endpoints)

  • Create chat sessions
  • Ask questions (single and multi-document)
  • RAG queries (Pro+)
  • Message history
  • Session management

Search (4 endpoints)

  • Semantic search
  • Keyword search
  • Hybrid search
  • Enhanced search (Pro+)

Folders (8 endpoints)

  • Create, list, update, delete
  • Nested folder support
  • Folder permissions

Webhooks (5 endpoints)

  • Create and manage webhooks
  • Event types
  • Webhook verification

Rate Limits

Archivus enforces rate limits based on your subscription tier:

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

See the Rate Limits guide for detailed information.

SDKs & Libraries

Use our official SDKs to integrate Archivus:

Best Practices

Authentication

  1. Use API keys for server-to-server integrations
  2. Use JWT tokens for web/mobile applications
  3. Store tokens securely - Never commit to version control
  4. Refresh tokens before expiration

Error Handling

  1. Always check status codes - Handle 4xx and 5xx errors
  2. Retry with exponential backoff - For transient errors
  3. Log errors - For debugging and monitoring
  4. Handle rate limits - Implement rate limit handling

Performance

  1. Use pagination - Don’t fetch all data at once
  2. Cache responses - Reduce API calls
  3. Batch operations - Use batch endpoints when available
  4. Monitor rate limits - Stay within your tier limits

Next Steps

Support

Ready to get started? Check out the Authentication guide to begin integrating with Archivus!

Table of contents