Aevum Encyclopedia

# Overview

The Aevum Encyclopedia API provides programmatic access to over 2.4 million verified articles across 140+ languages. Whether you're building a research tool, educational platform, or AI-powered assistant, our RESTful API and SDKs make integration straightforward.

🔍

Semantic Search

Context-aware search that understands intent, not just keywords.

🧠

AI-Powered Insights

Get AI-generated summaries, connections, and explanations.

🌐

Multilingual Access

Access content in 140+ languages with auto-translation.

📊

Knowledge Graphs

Explore relationships between concepts programmatically.

# Quick Start

Get up and running in under a minute with our JavaScript SDK.

Installation

                        Terminal
                        
                    
# Using npm
npm install @aevum/encyclopedia

# Using yarn
yarn add @aevum/encyclopedia

# Using pnpm
pnpm add @aevum/encyclopedia

Basic Usage

                        JavaScript
                        
                    
import { AevumEncyclopedia, SearchOptions } from '@aevum/encyclopedia';

// Initialize the client
const aevum = new AevumEncyclopedia({
  apiKey: process.env.AEVUM_API_KEY
});

// Search for articles
const results = await aevum.search({
  query: 'quantum entanglement',
  language: 'en',
  maxResults: 10
});

console.log(`Found ${results.total} articles`);
results.articles.forEach((article) => {
  console.log(`- ${article.title}`);
});

💡 Tip

Set your API key as an environment variable for security. Never hardcode credentials in your source code.

# Search API

The Search endpoint provides semantic, context-aware search across all encyclopedia content. It understands synonyms, related concepts, and user intent.

GET /v1/articles/search

Search for articles using natural language queries with optional filters.

Parameter	Type	Required	Description
q	string	Required	Search query (natural language)
lang	string	Optional	Language code (e.g., 'en', 'fr', 'ja')
category	string	Optional	Filter by category slug
limit	number	Optional	Max results (default: 20, max: 100)
semantic	boolean	Optional	Enable semantic search (default: true)

Search Examples

                        Python
                        
                    
from aevum import Client

client = Client(api_key="your-api-key")

# Basic search
results = client.search(
    query="photosynthesis in plants",
    language="en",
    category="biology",
    limit=5
)

for article in results["articles"]:
    print(article.title, article.summary)

                        cURL
                        
                    
curl "https://api.aevum.io/v1/articles/search?q=photosynthesis&lang=en&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

                        Response (JSON)
                        
                    
{
  "total": 1247,
  "query": "photosynthesis in plants",
  "articles": [
    {
      "id": "bio-photosynthesis-001",
      "title": "Photosynthesis",
      "summary": "Photosynthesis is the process by which green plants and...",
      "relevance": 0.97,
      "category": "biology",
      "language": "en",
      "lastUpdated": "2025-01-15T10:30:00Z"
    }
  ]
}

# Fetch Articles

Retrieve full article content by ID or slug, including all metadata, references, and multimedia assets.

                        JavaScript
                        
                    
// Fetch a single article by ID
const article = await aevum.getArticle('bio-photosynthesis-001');

console.log(article.title);           // "Photosynthesis"
console.log(article.content.html);   // Full HTML content
console.log(article.references.length); // 23

// Fetch multiple articles by IDs
const batch = await aevum.getArticles([
  'bio-photosynthesis-001',
  'bio-chloroplast-004',
  'chem-organic-compounds-012'
]);

// Fetch article with translation
const translated = await aevum.getArticle(
  'bio-photosynthesis-001',
  { language: 'es', includeRelated: true }
);

ℹ️ Rate Limits

Free tier: 100 requests/minute. Pro tier: 1,000 requests/minute. Enterprise: Custom limits. Each request includes X-RateLimit-Remaining header.

# Knowledge Graph

Query the underlying knowledge graph to discover relationships between concepts, entities, and topics.

                        Python
                        
                    
from aevum import Client

client = Client(api_key="your-api-key")

# Get related concepts
graph = client.knowledge_graph(
    entity="quantum mechanics",
    depth=2,
    max_connections=50
)

# Nodes in the graph
for node in graph["nodes"]:
    print(node["label"], node["type"])

# Relationships
for edge in graph["edges"]:
    print(edge["source"], edge["relation"], edge["target"])

                        Response (JSON)
                        
                    
{
  "center": "quantum mechanics",
  "nodes": [
    { "id": "qm-001", "label": "Quantum Mechanics", "type": "concept" },
    { "id": "ph-042", "label": "Wave-Particle Duality", "type": "concept" },
    { "id": "ph-089", "label": "Heisenberg Uncertainty Principle", "type": "principle" }
  ],
  "edges": [
    { "source": "qm-001", "relation": "includes", "target": "ph-042" },
    { "source": "qm-001", "relation": "includes", "target": "ph-089" }
  ]
}

# AI Insights

Leverage our AI engine to generate summaries, explanations, cross-references, and intelligent Q&A.

                        JavaScript
                        
                    
// Generate an AI-powered summary
const summary = await aevum.ai.summarize({
  articleId: 'hist-renaissance-art-007',
  length: 'medium',        // 'short' | 'medium' | 'long'
  language: 'en'
});

console.log(summary.text);

// Ask a question about an article
const answer = await aevum.ai.ask({
  articleId: 'bio-photosynthesis-001',
  question: 'What are the main stages of photosynthesis?'
});

// Discover connections between topics
const connections = await aevum.ai.connect({
  topics: ['machine learning', 'neuroscience']
});

# Translations

Access content in any of 140+ supported languages, or use the translation endpoint to dynamically translate articles.

                        Python
                        
                    
from aevum import Client

client = Client(api_key="your-api-key")

# Translate an article to French
translated = client.translate(
    article_id="bio-photosynthesis-001",
    target_language="fr"
)

print(translated["title"])
# "Photosynthèse"

print(translated["language"])
# "fr"

# Batch translate multiple articles
batch = client.translate_batch(
    article_ids=["a", "b", "c"],
    target_language="ja"
)

💡 Pro Tip

For frequently accessed content, consider caching translations. The API supports ETags for efficient conditional requests.

# Embed Widgets

Add interactive encyclopedia widgets to your website with a single line of code.

                        HTML
                        
                    
<!-- Search Widget -->
<div class="aevum-widget-search"
     data-lang="en"
     data-theme="dark"
     data-placeholder="Search Aevum Encyclopedia..."></div>

<!-- Article Embed -->
<div class="aevum-widget-article"
     data-article-id="bio-photosynthesis-001"
     data-lang="en"
     data-height="600px"></div>

<!-- Knowledge Graph Embed -->
<div class="aevum-widget-graph"
     data-entity="quantum mechanics"
     data-depth="2"
     data-width="100%"
     data-height="500px"></div>

<!-- Load the widget script -->
<script src="https://cdn.aevum.io/widget/v1.js"></script>

# Webhooks

Subscribe to real-time notifications when articles are updated, new content is published, or verification status changes.

                        JavaScript
                        
                    
// Register a webhook
const webhook = await aevum.webhooks.create({
  url: 'https://your-app.com/webhooks/aevum',
  events: [
    'article.created',
    'article.updated',
    'article.verified'
  ],
  secret: 'whsec_your_webhook_secret'
});

// Handle incoming webhook
app.post('/webhooks/aevum', async (req, res) => {
  const signature = req.headers['x-aevum-signature'];
  const payload = req.body;

  if (verifySignature(payload, signature)) {
    console.log(`Event: ${payload.type}`);
    console.log(`Article: ${payload.data.articleId}`);
    res.status(200).send('OK');
  }
});

# Batch Processing

Efficiently process multiple requests in a single API call using the batch endpoint.

                        Python
                        
                    
from aevum import Client

client = Client(api_key="your-api-key")

# Batch requests
batch_response = client.batch({
    "/v1/articles/bio-photosynthesis-001": { "method": "GET" },
    "/v1/articles/bio-chloroplast-004": { "method": "GET" },
    "/v1/articles/search": {
        "method": "POST",
        "body": { "q": "cellular respiration", "limit": 3 }
    }
})

# Access responses by path
article1 = batch_response["/v1/articles/bio-photosynthesis-001"]
search_results = batch_response["/v1/articles/search"]

⚠️ Limit

Batch requests are limited to 25 operations per call. Each operation counts against your rate limit individually.

# Examples by Use Case

Real-world integration patterns for common scenarios.

Building a Research Dashboard

                        React
                        
                    
import { useState, useEffect } from 'react';
import { AevumEncyclopedia } from '@aevum/encyclopedia';

const aevum = new AevumEncyclopedia({ apiKey: process.env.NEXT_PUBLIC_AEVUM_KEY });

export function ResearchDashboard() {
  const [topics, setTopics] = useState([]);
  const [graph, setGraph] = useState(null);

  const analyzeTopic = async (topic) => {
    const [articles, graphData, insights] = await Promise.all([
      aevum.search({ query: topic, limit: 20 }),
      aevum.knowledgeGraph({ entity: topic, depth: 3 }),
      aevum.ai.summary({ query: topic, length: 'long' })
    ]);

    setTopics(articles.articles);
    setGraph(graphData);
  };

  return (
    <div>
      <input onChange={(e) => analyzeTopic(e.target.value)} />
      <KnowledgeGraph data={graph} />
      <ArticleList articles={topics} />
    </div>);
}

Automated Content Verification

                        Python
                        
                    
from aevum import Client
import nltk

client = Client(api_key="your-api-key")

def verify_claims(text):
    """Extract factual claims and verify against Aevum Encyclopedia."""

    # Extract claims using NLP
    claims = extract_claims(text)

    results = []
    for claim in claims:
        search = client.search(query=claim, limit=3)

        verified = False
        sources = []

        for article in search["articles"]:
            if article["verification_status"] == "verified":
                verified = True
                sources.append(article["url"])

        results.append({
            "claim": claim,
            "verified": verified,
            "sources": sources
        })

    return results

Personalized Learning Paths

                        JavaScript
                        
                    
// Generate a learning path based on user interests
async function generateLearningPath(interests) {
  const path = [];

  for (const interest of interests) {
    const graph = await aevum.knowledgeGraph({
      entity: interest,
      depth: 2
    });

    const beginner = await aevum.search({
      query: `introduction to ${interest}`,
      limit: 5
    });

    path.push({
      topic: interest,
      starters: beginner.articles,
      connections: graph.edges,
      relatedTopics: graph.nodes.map(n => n.label)
    });
  }

  return path;
}

# Best Practices

Follow these guidelines to get the most out of the Aevum Encyclopedia API.

✅ Do

Use the batch endpoint for multiple related requests
Cache responses when content doesn't change frequently
Include If-None-Match headers with ETags for efficient caching
Use semantic search for natural language queries
Implement exponential backoff for rate limit retries
Verify webhook signatures before processing events

❌ Don't

Make individual requests in a loop — use batch instead
Ignore rate limit headers (X-RateLimit-Remaining)
Store API keys in client-side code
Scrape article content — use the API endpoints
Assume search results are ordered by date — use the sort parameter
Redistribute raw article content without attribution

Error Handling

                        JavaScript
                        
                    
try {
  const results = await aevum.search({
    query: 'some query',
    limit: 20
  });
} catch (error) {
  if (error.status === 429) {
    // Rate limited — wait and retry
    console.warn('Rate limited. Retrying in 1s...');
    await sleep(1000 * (1 + error.retryAfter));
  } else if (error.status === 404) {
    console.error('Article not found');
  } else if (error.status === 401) {
    console.error('Invalid API key');
  } else {
    console.error(`API Error ${error.status}:`, error.message);
  }
}

Usage Examples

# Overview

Semantic Search

AI-Powered Insights

Multilingual Access

Knowledge Graphs

# Quick Start

Installation

Basic Usage

# Search API

Search Examples

# Fetch Articles

# Knowledge Graph

# AI Insights

# Translations

# Embed Widgets

# Webhooks

# Batch Processing

# Examples by Use Case

Building a Research Dashboard

Automated Content Verification

Personalized Learning Paths

# Best Practices

Error Handling