CONFIGURATION REFERENCE

Configuration Syntax & Structure

Define how Aevum Encyclopedia SDKs, CLI tools, and server instances initialize, connect, and resolve knowledge graph queries.

Initialization Configuration

The primary configuration object accepts both JSON and YAML formats. It defines API routing, fallback behaviors, caching strategies, and knowledge graph resolution parameters.

JSON 
{
  "aevum": {
    "version": "3.2.1",
    "environment": "production",
    "api": {
      "base_url": "https://api.aevum.io/v1",
      "timeout_ms": 5000,
      "retries": 3,
      "retry_backoff": "exponential"
    },
    "graph": {
      "depth": 4,
      "expand_relations": true,
      "language_fallback": ["en", "es", "fr"]
    },
    "cache": {
      "enabled": true,
      "ttl_seconds": 3600,
      "strategy": "lru",
      "max_size_mb": 256
    }
  }
}
YAML 
aevum:
  version: "3.2.1"
  environment: production
  api:
    base_url: https://api.aevum.io/v1
    timeout_ms: 5000
    retries: 3
  graph:
    depth: 4
    expand_relations: true
    language_fallback:
      - en
      - es
  cache:
    enabled: true
    ttl_seconds: 3600
    strategy: lru
Note on Environment Detection
If environment is omitted, the SDK automatically resolves it from the AEVUM_ENV variable or defaults to development.

Environment Variables

Runtime configuration can be injected via environment variables. These override file-based configuration when present.

Variable Type Default Description
AEVUM_API_KEY string "" Master authentication token for API access
AEVUM_BASE_URL string https://api.aevum.io/v1 Custom endpoint for self-hosted or regional instances
AEVUM_TIMEOUT_MS number 5000 Maximum request timeout in milliseconds
AEVUM_LOG_LEVEL string "warn" Logging verbosity: debug, info, warn, error
AEVUM_CACHE_ENABLED boolean true Toggle in-memory knowledge graph caching
AEVUM_RATE_LIMIT number 1000 Requests per minute per API key

Core API Endpoints

All endpoints require a valid Authorization: Bearer <token> header unless marked as public.

Method Endpoint Auth Description
GET /v1/articles/{id} Required Retrieve full article payload with metadata
GET /v1/search Required Semantic search across the knowledge graph
GET /v1/graph/{id}/relations Required Fetch connected nodes and edge weights
POST /v1/auth/token Public Exchange API key for short-lived JWT
POST /v1/verify/citation Required Validate source URLs against trusted registry
Rate Limiting
Free tier is capped at 100 req/min. Enterprise plans support dynamic scaling up to 50,000 req/min with circuit breaker patterns enabled by default.

Authentication Flow

Aevum uses a two-tier authentication model: API keys for service-to-service communication, and JWT tokens for stateless request signing.

cURL 
curl -X POST https://api.aevum.io/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "ak_live_...", "scope": "read:graph"}'

Response includes access_token (valid 1h) and refresh_token (valid 30d). Tokens must be attached to all subsequent requests:

HTTP Header 
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...