Structural & Functional Changes

The offset-based pagination (?offset=&limit=) has been replaced with cursor-based pagination (?cursor=&page_size=) for improved performance on large result sets.

{
  "data": [ ... ],
  "pagination": {
    "total": 1250,
    "offset": 0,
    "limit": 20
    "cursor": "eyJpZCI6MjAsImNyZWF0ZWRfYXQiOiIyMDI1LTA2LTAxIn0",
    "has_more": true,
    "page_size": 20
  }
}

All v4 API responses now use application/hal+json as the Content-Type, including HAL links for navigation. The _links and _embedded keys are now standard in all responses.

{
  "id": "art_8x29m4k",
  "title": "Quantum Computing",
  "_links": {
    "self": { "href": "/v4/articles/art_8x29m4k" },
    "categories": { "href": "/v4/articles/art_8x29m4k/categories" },
    "graph": { "href": "/v4/knowledge-graph/nodes/art_8x29m4k" }
  }
}

Rate limit headers have been changed to align with RFC 6585 (Extended HTTP Status Codes). Limits are now per-endpoint rather than global.

The core article data model has been restructured to support multi-language content, versioned editing, and provenance tracking. Several top-level fields have been moved or renamed.

All resource IDs now use a prefixed format (type_identifier) for type safety and collision avoidance. Simple numeric IDs are no longer accepted.

# Old format
{
  "id": 12345,
  "article": 12345
}

# New format
{
  "id": "art_8x29m4k",
  "category": "cat_physics",
  "contributor": "usr_a1b2c3d"
}

The authentication system has been upgraded to OAuth 2.1 per RFC 9207. The access_type=offline parameter is no longer supported; use the refresh_token grant type explicitly.

# Old (OAuth 2.0)
GET /oauth/authorize?
  client_id=xxx&
  response_type=code&
  scope=read&
  access_type=offline

# New (OAuth 2.1)
GET /oauth/authorize?
  client_id=xxx&
  response_type=code&
  scope=read

# Refresh tokens must be requested explicitly
POST /oauth/token
  grant_type=refresh_token&
  refresh_token=xxx&
  scope=read

Additionally, token lifetimes have been reduced: access tokens now expire in 15 minutes (was 1 hour), and refresh tokens expire in 7 days (was 30 days).

The knowledge graph engine has been rebuilt from the ground up. v2 introduces three new relationship types that were not possible in v1:

• causation — Direct cause-effect relationships between events and phenomena
• contradiction — Identifies conflicting claims between articles with source citations
• temporal — Time-based relationships showing evolution of concepts across eras

GET /v4/knowledge-graph/edges?
  source=art_8x29m4k&
  type=causation,contradiction,temporal

# Returns graph edges with confidence scores
{
  "edges": [
    {
      "type": "causation",
      "source": "art_8x29m4k",
      "target": "art_q9r1s2t",
      "confidence": 0.94,
      "sources": 12
    }
  ]
}

A new search engine powered by a fine-tuned large language model enables natural language queries with context-aware ranking. This replaces the legacy keyword-based search as the primary search method.

POST /v4/search/semantic
{
  "query": "What led to the development of quantum error correction,\nand how does it relate to fault-tolerant computing?",
  "depth": "multi-hop",
  "context": "research-level"
}

The search now returns ranked results with relevance scores, extracted snippets, and automatic source attribution.

WebSocket connections now allow real-time article update streaming. Subscribers receive delta updates when content changes, moderation actions occur, or new articles are published in watched categories.

WS wss://stream.aevum.com/v4/realtime?token=xxx

// Subscribe to category updates
→ { "action": "subscribe", "category": "cat_physics" }

// Receive real-time events
← { "event": "article.updated", "article": "art_8x29m4k", "delta": {...} }
← { "event": "article.created", "article": "art_new1234", "category": "cat_physics" }

A new webhook infrastructure allows integrations to receive HTTP POST notifications for platform events. Supports configurable retry policies, signature verification, and event filtering.

{
  "id": evt_9a8b7c6d,
  "type": "article.fact_checked",
  "timestamp": "2025-06-01T14:32:00Z",
  "data": {
    "article_id": "art_8x29m4k",
    "verdict": "verified",
    "confidence": 0.97
  }
}

// Headers include signature verification
X-Aevum-Signature: sha256=abc123...
X-Aevum-Event-ID: evt_9a8b7c6d

The keyword search ranking algorithm has been updated to incorporate recency, verification status, and cross-reference density. Results are now weighted more heavily toward recently verified and well-sourced articles.

New query parameters available:

GET /v4/search?query=photosynthesis&
  ranking_strategy=relevance|recency|verification&
  min_verification=high|medium|low&
  include_cross_refs=true

The article ingestion pipeline now includes two new mandatory stages before publication:

1. Stage 3 — AI Fact-Checking: Automatic verification of claims against indexed primary sources. Claims below 0.8 confidence are flagged for human review.
2. Stage 4 — Source Triangulation: Each factual claim must be supported by at least 2 independent credible sources before the article is marked as "verified.""

Articles that fail Stage 3 or 4 are placed in status:pending_review and notify the original contributor for revision.

Cache invalidation has changed from time-based (TTL) to event-driven (TTL + pub/sub). This means content updates are reflected in cache immediately rather than waiting for TTL expiry.

Cache headers updated:

Multiple infrastructure changes have resulted in significant performance gains:

The following endpoints are deprecated and will be removed on July 20, 2025:

Deprecated endpoints return Sunset: Sat, 20 Jul 2025 00:00:00 GMT and Deprecation: true headers.

Several response fields are deprecated and will return null or be removed entirely:

All API connections now require TLS 1.3. TLS 1.2 connections will be rejected starting August 1, 2025. Earlier clients must upgrade their TLS stack.

# Minimum required cipher suites
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256

# Client certificate rotation
Certificate validity reduced from 365 to 90 days
Automatic rotation via ACME protocol supported

Enterprise tier integrations can now configure IP allowlists via the dashboard or API. Requests from non-allowlisted IPs will receive a 403 Forbidden response.

POST /v4/enterprise/security/ip-allowlist
{
  "allowed_ips": [
    "203.0.113.0/24",
    "198.51.100.0/24"
  ],
  "mode": "strict"
}