Implementation Guidelines — Aevum Encyclopedia

Overview

Aevum Encyclopedia provides a unified, RESTful API and modular frontend components for accessing verified, multilingual knowledge content. This guide covers authentication, request formatting, embed implementation, SDK usage, and operational best practices.

ℹ️ Architecture Note

All API responses follow JSON:API v1.1 specifications. Content is versioned, cached at edge locations, and delivered via HTTPS with strict CORS policies.

Prerequisites

Active Aevum Developer account with API access enabled
Project-level API key (generated via Dashboard → Settings → API Keys)
HTTPS endpoint for webhook listeners
Node.js 18+ / Python 3.9+ / or compatible runtime for SDK usage

Authentication

Aevum uses Bearer token authentication. All requests must include your API key in the Authorization header. Tokens expire after 24 hours and must be refreshed via the /auth/refresh endpoint.

HTTP

GET https://api.aevum-encyclopedia.com/v3/articles
Authorization: Bearer <your_api_token>
Content-Type: application/json

Token Refresh Flow

JavaScript

const response = await fetch('https://api.aevum-encyclopedia.com/v3/auth/refresh', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AEVUM_REFRESH_TOKEN}`
  }
});
const data = await response.json();
console.log(data.access_token);

Core API Endpoints

Method	Endpoint	Description	Status
`GET`	`/v3/articles/{id}`	Retrieve full article content, citations, and metadata	Stable
`GET`	`/v3/search`	Semantic search with filtering, ranking, and language parameters	Stable
`GET`	`/v3/graph/{concept}`	Fetch knowledge graph nodes and relationship edges	Beta
`POST`	`/v3/bulk/fetch`	Batch retrieval for up to 50 article IDs per request	Stable

⚠️ Deprecation Notice

Endpoints prefixed with /v2/ will be sunset on March 31, 2026. Migrate to v3 using the automated migration tool in your developer dashboard.

Embed Widgets

Quickly integrate Aevum's verified content viewer, citation carousel, or interactive knowledge graph into any web project using our lightweight iframe component.

Standard Article Embed

HTML

<iframe
  src="https://embed.aevum-encyclopedia.com/v1/article/quantum-computing?theme=dark&lang=en"
  width="100%"
  height="600"
  frameborder="0"
  allow="fullscreen; clipboard-write"
  title="Aevum Encyclopedia Embed"
></iframe>

Configuration Parameters

Parameter	Type	Default	Description
`theme`	string	light	UI theme: `light`, `dark`, or `auto`
`lang`	string	en	ISO 639-1 language code for content localization
`height`	number	600	Minimum viewport height in pixels
`hideHeader`	boolean	false	Remove navigation bar for seamless integration

SDKs & Libraries

Official client libraries are available for JavaScript/TypeScript, Python, and Go. All SDKs handle authentication, retries, pagination, and type safety automatically.

NPM / Yarn

npm install @aevum/encyclopedia-sdk
# or
yarn add @aevum/encyclopedia-sdk

TypeScript

import { AevumClient } from '@aevum/encyclopedia-sdk';

const client = new AevumClient({
  apiKey: process.env.AEVUM_API_KEY,
  region: 'us-east-1',
  cacheEnabled: true
});

const article = await client.articles.retrieve('quantum-computing');
console.log(article.title, article.verified);

Rate Limits & Quotas

API usage is governed by tiered rate limits to ensure platform stability. All limits are calculated per API key using a sliding window algorithm.

Tier	Requests/min	Search/min	Graph Queries/min	Monthly Quota
Free	60	10	5	5,000 calls
Developer	300	60	30	50,000 calls
Enterprise	Custom	Custom	Custom	Unlimited

✅ Exceeded Limits?

Responses include X-RateLimit-Remaining and Retry-After headers. Implement exponential backoff to avoid 429 Too Many Requests errors.

Best Practices

Cache Aggressively: Articles rarely change. Use Cache-Control: max-age=3600 for static content and validate with ETag headers.
Use Semantic IDs: Always reference content via UUIDs rather than slugs to prevent 404s during restructuring.
Batch Operations: Use /bulk/fetch instead of sequential calls to reduce latency and API overhead.
Respect Citation Boundaries: Do not strip or modify source attribution. Aevum's content license requires intact citation metadata.

Troubleshooting

Common Error Codes

Code	Meaning	Resolution
`401`	Invalid or expired token	Refresh your API key or check clock sync
`403`	Permission denied / quota exceeded	Verify plan tier or contact support for upgrade
`422`	Malformed request payload	Validate against JSON schema in Swagger docs
`503`	Service degradation	Check status.aevum-encyclopedia.com

⚠️ Cross-Origin Issues

If using embed widgets locally, serve via localhost or HTTPS. Browsers block insecure iframe contexts. Use http://localhost:3000 for development.