Searching Documents

Learn how to find documents quickly using Archivus’s powerful search capabilities.

Search Overview

Archivus provides multiple search methods:

Semantic Search - Find by meaning (AI-powered)
Keyword Search - Find by exact text matches
Hybrid Search - Combines both methods
Filtered Search - Search with filters (folder, tag, date, etc.)

Quick Search

Basic Search

curl "https://api.archivus.app/api/v1/search?q=contract+renewal" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant"

Response:

{
  "results": [
    {
      "document": {
        "id": "doc_abc123",
        "filename": "service-agreement.pdf",
        "ai_summary": "Service agreement with renewal terms..."
      },
      "score": 0.92,
      "relevance": "high"
    }
  ],
  "mode": "semantic",
  "query": "contract renewal",
  "total": 5
}

Search Modes

Semantic Search (Recommended)

Finds documents by meaning, not just keywords:

curl "https://api.archivus.app/api/v1/search?q=find+all+contracts+expiring+soon&mode=semantic" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant"

Best for:

Natural language queries
Finding related concepts
Discovering documents without exact keywords

Keyword Search

Traditional text-based search:

curl "https://api.archivus.app/api/v1/search?q=contract+renewal&mode=text" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant"

Best for:

Exact phrase matching
Short queries (< 10 characters)
Specific terms or codes

Automatic Mode

Archivus automatically chooses the best mode:

# Short query    keyword search
curl "https://api.archivus.app/api/v1/search?q=tax"

# Long query    semantic search
curl "https://api.archivus.app/api/v1/search?q=find+all+tax+documents+from+last+year"

Filter by Folder

curl "https://api.archivus.app/api/v1/search?q=contract&folder_id=folder_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant"

Filter by Tag

curl "https://api.archivus.app/api/v1/search?q=contract&tag_id=tag_legal" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant"

Filter by File Type

curl "https://api.archivus.app/api/v1/search?q=contract&file_type=application/pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant"

Filter by Date Range

curl "https://api.archivus.app/api/v1/search?q=contract&date_start=2025-01-01&date_end=2025-12-31" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant"

Combine Filters

curl "https://api.archivus.app/api/v1/search?q=contract&folder_id=folder_abc123&tag_id=tag_legal&file_type=application/pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant"

Advanced Search

Enhanced Search (Pro+)

AI-enhanced search with advanced filtering:

curl -X POST https://api.archivus.app/api/v1/search/enhanced \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Find all contracts expiring in Q4 2025",
    "filters": {
      "date_range": {
        "start": "2025-10-01",
        "end": "2025-12-31"
      },
      "tags": ["contract"],
      "ai_categories": ["legal"],
      "folder_id": "folder_legal"
    },
    "include_similar": true,
    "min_score": 0.7
  }'

Hybrid Search

Combine semantic and keyword search:

curl -X POST https://api.archivus.app/api/v1/search/hybrid \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "contract renewal terms",
    "semantic_weight": 0.7,
    "text_weight": 0.3,
    "limit": 20
  }'

Code Examples

Python - Search Documents

import requests

class ArchivusSearch:
    def __init__(self, api_key, tenant):
        self.api_key = api_key
        self.tenant = tenant
        self.base_url = "https://api.archivus.app/api/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "X-Tenant-Subdomain": tenant
        }
    
    def search(self, query, mode="auto", **filters):
        url = f"{self.base_url}/search"
        params = {"q": query, "mode": mode}
        
        # Add filters
        if "folder_id" in filters:
            params["folder_id"] = filters["folder_id"]
        if "tag_id" in filters:
            params["tag_id"] = filters["tag_id"]
        if "file_type" in filters:
            params["file_type"] = filters["file_type"]
        if "limit" in filters:
            params["limit"] = filters["limit"]
        
        response = requests.get(url, headers=self.headers, params=params)
        return response.json()
    
    def enhanced_search(self, query, filters=None):
        url = f"{self.base_url}/search/enhanced"
        data = {"query": query}
        if filters:
            data["filters"] = filters
        
        response = requests.post(url, headers=self.headers, json=data)
        return response.json()

# Usage
search = ArchivusSearch("YOUR_API_KEY", "your-tenant")

# Basic search
results = search.search("contract renewal")

# Filtered search
results = search.search(
    "contract",
    folder_id="folder_legal",
    tag_id="tag_urgent",
    limit=10
)

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

JavaScript - Search Documents

class ArchivusSearch {
  constructor(apiKey, tenant) {
    this.apiKey = apiKey;
    this.tenant = tenant;
    this.baseURL = 'https://api.archivus.app/api/v1';
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'X-Tenant-Subdomain': tenant
    };
  }
  
  async search(query, mode = 'auto', filters = {}) {
    const url = new URL(`${this.baseURL}/search`);
    url.searchParams.set('q', query);
    url.searchParams.set('mode', mode);
    
    // Add filters
    Object.entries(filters).forEach(([key, value]) => {
      if (value) url.searchParams.set(key, value);
    });
    
    const response = await fetch(url, { headers: this.headers });
    return response.json();
  }
  
  async enhancedSearch(query, filters = {}) {
    const response = await fetch(`${this.baseURL}/search/enhanced`, {
      method: 'POST',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify({ query, filters })
    });
    return response.json();
  }
}

// Usage
const search = new ArchivusSearch('YOUR_API_KEY', 'your-tenant');

// Basic search
const results = await search.search('contract renewal');

// Filtered search
const filteredResults = await search.search('contract', 'semantic', {
  folder_id: 'folder_legal',
  tag_id: 'tag_urgent',
  limit: 10
});

// Enhanced search
const enhancedResults = await search.enhancedSearch(
  'Find all contracts expiring in Q4',
  {
    date_range: {
      start: '2025-10-01',
      end: '2025-12-31'
    },
    tags: ['contract']
  }
);

Understanding Results

Score

Each result has a relevance score (0.0 to 1.0):

0.8 - 1.0: Highly relevant
0.6 - 0.8: Relevant
0.4 - 0.6: Somewhat relevant
< 0.4: Low relevance

Relevance Level

Human-readable relevance:

"high" - Score 0.7
"medium" - Score 0.4 - 0.7
"low" - Score < 0.4

Result Structure

{
  "results": [
    {
      "document": {
        "id": "doc_abc123",
        "filename": "contract.pdf",
        "ai_summary": "...",
        "highlight": "...matching text..."
      },
      "score": 0.92,
      "relevance": "high"
    }
  ],
  "mode": "semantic",
  "query": "contract renewal",
  "total": 5
}

Best Practices

Query Tips

Use natural language - “Find contracts expiring soon”
Be specific - “Q4 2025 service contracts”
Combine with filters - Use semantic search + folder filter
Try different phrasings - If no results, rephrase query

Performance

Use filters - Narrow search scope for faster results
Limit results - Use limit parameter (default: 20)
Cache results - Store results client-side when possible

Search Strategy

Start broad - Use semantic search to discover documents
Narrow down - Add filters based on initial results
Refine query - Adjust query based on results quality

Search Tips

Finding Specific Documents

By filename:

curl "https://api.archivus.app/api/v1/search?q=Q4-Contract-2025&mode=text"

By content:

curl "https://api.archivus.app/api/v1/search?q=service+agreement+renewal+terms&mode=semantic"

Use semantic search to find related content:

curl "https://api.archivus.app/api/v1/search?q=documents+similar+to+contract+abc123&mode=semantic"

Finding Recent Documents

Combine search with date filter:

curl "https://api.archivus.app/api/v1/search?q=contract&date_start=2025-12-01"

Next Steps

Semantic Search Guide - Deep dive into semantic search
Sharing Documents - Share search results
API Reference - Complete search API documentation

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