Search API¶

Semantic and keyword search across your document collection.

Overview¶

The Search API provides powerful document discovery capabilities:

• Semantic Search - Find documents by meaning, not just keywords
• Keyword Search - Traditional full-text search
• Hybrid Search - Combine semantic and keyword approaches
• Advanced Filters - Filter by date, folder, file type, and more

Basic Search¶

Perform semantic or keyword search across documents.

GET /api/v1/search

Query Parameters¶

Example Request¶

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

const params = new URLSearchParams({
  q: 'contract renewal terms',
  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 terms',
    '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()

Response¶

{
  "results": [
    {
      "document": {
        "id": "doc_abc123",
        "filename": "service-agreement.pdf",
        "ai_summary": "Service agreement with renewal terms...",
        "folder_id": "folder_legal",
        "created_at": "2026-01-15T10:00:00Z"
      },
      "score": 0.92,
      "relevance": "high",
      "highlight": "...renewal terms effective upon expiration..."
    },
    {
      "document": {
        "id": "doc_def456",
        "filename": "vendor-contract.pdf",
        "ai_summary": "Vendor agreement with auto-renewal clause..."
      },
      "score": 0.85,
      "relevance": "high",
      "highlight": "...automatic renewal unless terminated..."
    }
  ],
  "mode": "semantic",
  "query": "contract renewal terms",
  "total": 5
}

Search Modes¶

Automatic Mode (Recommended)¶

Archivus automatically chooses the best search mode:

• Short queries (< 10 characters) → Keyword search
• Long queries (≥ 10 characters) → Semantic search

curl "https://api.archivus.app/api/v1/search?q=find+all+contracts+expiring+in+Q4" \
  -H "X-API-Key: ak_live_YOUR_API_KEY"

Semantic Search¶

Find documents by meaning using AI embeddings:

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

Best for: - Natural language queries - Conceptual searches - Finding similar documents - Cross-language understanding

Keyword Search¶

Traditional full-text search:

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

Best for: - Exact phrase matching - Document IDs or codes - Specific terminology - Fast lookups

Enhanced Search (Pro+)¶

AI-enhanced search with advanced filtering and context understanding.

POST /api/v1/search/enhanced

Request Body¶

{
  "query": "Find all contracts expiring in Q4 2026",
  "filters": {
    "date_range": {
      "start": "2026-10-01",
      "end": "2026-12-31"
    },
    "tags": ["contract"],
    "ai_categories": ["legal"],
    "folder_id": "folder_legal"
  },
  "include_similar": true,
  "min_score": 0.7
}

Example Request¶

curl -X POST https://api.archivus.app/api/v1/search/enhanced \
  -H "X-API-Key: ak_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Find all contracts expiring in Q4",
    "filters": {
      "tags": ["contract"],
      "date_range": {
        "start": "2026-10-01",
        "end": "2026-12-31"
      }
    }
  }'

const response = await fetch('https://api.archivus.app/api/v1/search/enhanced', {
  method: 'POST',
  headers: {
    'X-API-Key': 'ak_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'Find all contracts expiring in Q4',
    filters: {
      tags: ['contract'],
      date_range: {
        start: '2026-10-01',
        end: '2026-12-31'
      }
    }
  })
});

response = requests.post(
    'https://api.archivus.app/api/v1/search/enhanced',
    json={
        'query': 'Find all contracts expiring in Q4',
        'filters': {
            'tags': ['contract'],
            'date_range': {
                'start': '2026-10-01',
                'end': '2026-12-31'
            }
        }
    },
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'}
)

Hybrid Search¶

Combine semantic and keyword search with custom weighting.

POST /api/v1/search/hybrid

Request Body¶

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

Scoring: score = (semantic_weight × semantic_score) + (text_weight × text_score)

Understanding Results¶

Relevance Scores¶

Scores range from 0.0 to 1.0:

Highlights¶

Search results include text highlights showing matching context:

{
  "highlight": "...the renewal terms are effective upon expiration of the initial term..."
}

AI Credits Cost¶

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 query",
  "total": 0
}

Next Steps¶