Scripting & Communication Standards v3.2

Overview

Aevum Encyclopedia exposes a unified scripting environment and communication layer designed for high-throughput knowledge retrieval, contribution pipelines, and real-time synchronization. This document outlines the standards, endpoints, and best practices for developers integrating with our platform.

Scripting Framework

Contributors and partners can extend Aevum's behavior using AevumScript, a sandboxed JavaScript runtime compatible with ES2024 features. Scripts are executed in isolated V8 contexts with strict CSP policies.

Core capabilities include:

• Knowledge graph traversal via ae.graph.query()
• Automated citation formatting and cross-referencing
• Webhook triggers for editorial workflow automation
• Local caching strategies for offline contribution sync

Communication Protocols

Aevum supports three primary communication channels depending on your use case:

GraphQL Support

For complex knowledge graph traversals, use our GraphQL endpoint at api.aevum.org/v3/graphql. It supports batching, pagination via cursor, and schema introspection.

Authentication & Security

All API requests require OAuth 2.0 Bearer tokens. Client credentials flow is supported for server-to-server integrations, while authorization code flow is required for user-facing applications.

curl -X GET https://api.aevum.org/v3/articles/quantum-mechanics \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Accept: application/ld+json"

Tokens expire after 3600 seconds. Implement automatic refresh logic using the refresh_token grant. Never expose secrets in client-side code.

Rate Limiting

To maintain service stability, endpoints are subject to tiered rate limits:

• Free Tier: 100 requests/minute, 50 concurrent WebSocket connections
• Academic/Partner: 1,000 requests/minute, 200 concurrent connections
• Enterprise: Custom limits, dedicated throughput allocation

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 942
X-RateLimit-Reset: 1698765432
Retry-After: 45  (only on 429)

Error Handling

Aevum uses standard HTTP status codes alongside structured JSON error payloads. All errors follow RFC 7807 (Problem Details for HTTP APIs).

{
  "type": "https://api.aevum.org/errors/rate-limited",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Maximum request quota reached for this tier.",
  "instance": "/v3/articles/search?q=encyclopedia",
  "meta": {
    "retry_after": 12,
    "quota_reset": "2025-04-12T14:30:00Z"
  }
}

Code Examples

JavaScript Fetch Integration

async function fetchArticle(slug) {
  const response = await fetch(`https://api.aevum.org/v3/articles/${slug}`, {
    headers: {
      'Authorization': `Bearer ${process.env.AE_TOKEN}`,
      'Accept': 'application/ld+json'
    }
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.detail || 'Request failed');
  }

  return response.json();
}

// Usage
fetchArticle('renewable-energy-systems')
  .then(data => console.log(data["@graph"].length, 'relations found'))
  .catch(console.error);

WebSocket Real-Time Stream

const ws = new WebSocket('wss://live.aevum.org/stream');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    channels: ['editorial.reviews', 'knowledge.updates'],
    token: process.env.AE_TOKEN
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'revision_update') {
    console.log(`[${msg.author}] updated section: ${msg.section_id}`);
    // Trigger UI diff or sync local draft
  }
};

Changelog

Review version history and breaking changes for scripting & communication modules:

• v3.2 (2025-04) - Added GraphQL batching, WebSocket reconnection resilience
• v3.1 (2025-02) - Deprecation of XML responses, JSON-LD enforced by default
• v3.0 (2024-11) - OAuth 2.0 migration, rate limit header standardization
• v2.8 (2024-08) - Initial AevumScript sandbox release

Need help? Contact dev-support@aevum.org or join our Developer Discord.