Search API

Complete API reference for search endpoints.

Perform semantic or keyword search across documents.

GET /api/v1/search

Query Parameters

Parameter Type Required Description
q string Yes Search query
mode string No semantic, text, or auto (default: auto)
folder_id string No Filter by folder
tag_id string No Filter by tag
file_type string No Filter by file type
date_start string No Filter by start date (ISO 8601)
date_end string No Filter by end date (ISO 8601)
limit integer No Max results (default: 20, max: 100)

Example 

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

Response 

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

Enhanced Search (Pro+)

AI-enhanced search with advanced filtering.

POST /api/v1/search/enhanced

Request 

{
  "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
}

Example 

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

Response

Enhanced results with AI insights and filtering.

Combine semantic and keyword search.

POST /api/v1/search/hybrid

Request 

{
  "query": "contract renewal terms",
  "semantic_weight": 0.7,
  "text_weight": 0.3,
  "limit": 20
}

Example 

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

Response

Results ranked by hybrid scoring (70% semantic + 30% keyword).

Search Modes

Archivus automatically chooses the best mode:

  • Short queries (< 10 chars): Uses keyword search
  • Long queries ( 10 chars): Uses semantic search
# Automatically uses semantic search
curl "https://api.archivus.app/api/v1/search?q=find+all+contracts+expiring+in+Q4"

Finds documents by meaning:

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

Traditional text-based search:

curl "https://api.archivus.app/api/v1/search?q=contract+renewal&mode=text"

Understanding Results

Score

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

Hybrid Scoring

Archivus uses hybrid scoring:

  • 70% semantic similarity (vector search)
  • 30% text relevance (keyword matching)

Code Examples

Python 

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}
        params.update(filters)
        
        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")
results = search.search("contract renewal", mode="semantic", limit=10)

JavaScript 

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);
    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');
const results = await search.search('contract renewal', 'semantic', { limit: 10 });

Cost

  • Semantic search: 0.5 AI credits per query
  • Enhanced search: 1 AI credit per query
  • Keyword search: Free (no AI credits)

Error Responses

Invalid Query

Status: 400 Bad Request

{
  "error": "invalid_query",
  "code": "INVALID_QUERY",
  "message": "Search query cannot be empty"
}

No Results

Status: 200 OK (with empty results)

{
  "results": [],
  "mode": "semantic",
  "query": "nonexistent",
  "total": 0
}

Next Steps

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