⚡ API Version 3.2.0

GraphQL API Reference

Programmatic access to Aevum Encyclopedia's knowledge base. Query articles, contributors, categories, and the dynamic knowledge graph with type-safe, efficient requests.

Overview

The GraphQL v3.2 endpoint provides a unified interface to explore, filter, and aggregate over 2.4 million verified encyclopedia entries. Unlike REST, GraphQL allows you to request exactly the data you need, reducing payload size by up to 70% while maintaining full type safety.

🌐 Base URL https://api.aevum-encyclopedia.com/graphql/v3.2
All requests must include the Content-Type: application/json header.

v3.2 introduces real-time subscriptions, optimized DataLoader batching, and expanded schema coverage for cross-disciplinary knowledge graph traversal.

Authentication

Access the API using Bearer tokens issued through your Developer Dashboard. Tokens are scoped by permission level and can be rotated without service interruption.

HTTP Header 
Authorization: Bearer <your_api_key>
X-Aevum-Version: 3.2
Scope Description Rate Limit
read:articles Query article metadata, content, and references 120 req/min
read:graph Traverse knowledge graph nodes and edges 80 req/min
write:annotations Submit verified corrections or tags 30 req/min

Core Schema Types

The v3.2 schema defines the foundational objects you'll interact with. All types support standard filtering, pagination, and projection.

GraphQL Schema 
type Article {
  id!: ID
  slug: String
  title!: String
  content: Markdown
  category: Category
  contributors: [Contributor]
  knowledgeNodes: [GraphNode]
  lastVerified: Timestamp
  language: String # ISO 639-1
}

type Category {
  id!: ID
  name: String
  parent: Category
  articleCount: Int
}

type Contributor {
  id!: ID
  name: String
  expertise: [String]
  verified: Boolean
}

Queries

Fetch articles with precise field selection. v3.2 supports fuzzy matching, semantic search, and cross-language resolution.

GraphQL Query 
query SearchArticles($query: String!, $lang: String = "en") {
  articles(filter: { semanticMatch: $query, language: $lang }, first: 10) {
    edges {
      node {
        id
        title
        category { name }
        lastVerified
        summary(length: 150)
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}
⚠️ Deprecation Notice The legacy searchTerms filter has been replaced by semanticMatch in v3.2. Use the migration guide to update client schemas.

Mutations

Submit corrections, request reviews, or annotate entries. All mutations are queued for expert verification before publication.

GraphQL Mutation 
mutation SubmitCorrection($input: CorrectionInput!) {
  submitCorrection(input: $input) {
    id
    status
    reviewerAssigned { name }
    estimatedReviewTime
  }
}

# Input shape
input CorrectionInput {
  articleId!: ID
  section: String
  original: String
  proposed!: String
  evidence: [String]
}

Subscriptions (v3.2 New)

Subscribe to real-time events using WebSockets. Useful for monitoring live editorial updates, trending topics, or knowledge graph expansions.

GraphQL Subscription 
subscription OnArticleUpdate($categories: [String]) {
  articleUpdated(filter: { categories: $categories }) {
    id
    title
    updatedAt
    changeType # EDIT, VERIFY, EXPAND
    affectedNodes { id, label }
  }
}
✅ WebSocket Endpoint wss://realtime.aevum-encyclopedia.com/graphql/v3.2
Authentication uses the same Bearer token. Reconnection is handled automatically by standard GraphQL WebSocket clients.

Knowledge Graph Traversal

v3.2 exposes the underlying semantic graph, allowing you to explore relationships between concepts across disciplines. Use graphPath to find conceptual bridges between articles.

Field Type Description
graphPath(start, end, maxDepth) [PathNode] Shortest conceptual route between two articles
neighbors(nodeId, limit) [GraphNode] Directly linked concepts with edge weights
clusterAnalysis(tags) Cluster Dense subgraphs for topic modeling

v3.2.0 Changelog

  • Added: Real-time subscriptions over WebSockets for editorial events and trending topics
  • Added: graphPath and neighbors resolvers for knowledge graph traversal
  • Improved: DataLoader batching reduces N+1 query overhead by ~65%
  • Changed: searchTerms deprecated in favor of semanticMatch with vectorized indexing
  • Fixed: Pagination cursor drift on filtered result sets
  • Fixed: Cross-language article resolution returning mixed encodings

For full migration steps from v3.1, see the Migration Guide. Legacy v2.x endpoints remain operational until Q2 2026 but will not receive new features.