📰 API Documentation v2.4

Enterprise API

Integrate Aevum News' comprehensive global journalism feed into your applications. Access real-time articles, advanced search, topic feeds, and streaming data with our robust RESTful API.

BASE URL https://api.aevumnews.com/v2
🔐 Get API Key 📦 View SDKs 💎 Pricing

🔐 Authentication

All API requests require authentication via API key. Include your key in the Authorization header.

ℹ️
API keys are tied to your enterprise account. Keep them secure and never expose them in client-side code. Use environment variables in production.
cURL 
curl https://api.aevumnews.com/v2/news \

  -H "Authorization: Bearer YOUR_API_KEY" \

  -H "Content-Type: application/json"
JavaScript (Fetch) 
const response = await fetch('https://api.aevumnews.com/v2/news', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.AEVUM_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data.articles); // Array of article objects
Python 
import requests

headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

response = requests.get(
  "https://api.aevumnews.com/v2/news",
  headers=headers
)

articles = response.json()["articles"]

🌐 Base URL & Versioning

All endpoints are versioned. Current stable version is v2. Version is included in the base URL path.

ℹ️
Current Version: v2.4.0 — Released January 2025
Previous Stable: v2.3 — Supported until July 2025
Legacy: v1 — Deprecated as of October 2024

⚡ Rate Limits

Rate limits are applied per API key and tier. Headers in each response indicate your current usage.

1,000
requests / minute (Starter)
10,000
requests / minute (Professional)
100,000
requests / minute (Enterprise)
∞
streaming connections
⚠️
Exceeding rate limits returns 429 Too Many Requests. Implement exponential backoff. Enterprise accounts can request custom limits.
Response Headers 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 947
X-RateLimit-Reset: 1704067200
X-RateLimit-Window: 60s

📋 API Endpoints

Complete reference for all available endpoints.

GET /v2/news Retrieve latest news articles

Description

Fetch a paginated feed of the latest news articles. Supports filtering by category, region, and date range.

Query Parameters

Parameter Type Required Description
page integer Optional Page number (default: 1)
per_page integer Optional Items per page (1-100, default: 20)
category string Optional Filter by category (politics, tech, business, world, science, culture)
region string Optional ISO 3166-1 alpha-2 region code
date_from string Optional Start date (ISO 8601: YYYY-MM-DD)
date_to string Optional End date (ISO 8601: YYYY-MM-DD)
sort string Optional Sort order: relevance, date, popularity

Example Request

cURL 
curl "https://api.aevumnews.com/v2/news?page=1&per_page=20&category=tech&sort=date" \

  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

JSON Response 
{
  "status": "success",
  "page": 1,
  "per_page": 20,
  "total_pages": 487,
  "total_results": 9734,
  "articles": [
    {
      "id": "art_8xK2mN9pQ1
      "headline": "AI Revolution: New Models Redefine Human-Computer Interaction",
      "summary": "Researchers unveil breakthrough AI systems with unprecedented context understanding...",
      "category": "technology",
      "tags": ["AI", "machine-learning", "innovation"],
      "author": "Marcus Chen",
      "published_at": "2025-01-15T09:30:00Z",
      "updated_at": "2025-01-15T10:15:00Z",
      "read_time": 5,
      "region": "global",
      "source": "Aevum Correspondent Network",
      "url": "https://www.aevumnews.com/articles/art_8xK2mN9pQ1,
      "image_url": "https://cdn.aevumnews.com/images/ai-revolution.jpg",
      "sentiment": "neutral",
      "verified": true
    }
  ]
}
200 OK 401 Unauthorized 429 Rate Limited
GET /v2/articles/:id Retrieve full article detail

Description

Fetch a single article by its unique ID, including full body text, metadata, related articles, and embedded media.

cURL 
curl "https://api.aevumnews.com/v2/articles/art_8xK2mN9pQ1" \

  -H "Authorization: Bearer YOUR_API_KEY"

Path Parameters

Parameter Type Required Description
id string Required Unique article identifier (e.g., art_8xK2mN9pQ1)
POST /v2/articles Submit an article for syndication

Description

Submit original content for syndication to Aevum News partners. Content is reviewed by editorial team within 24 hours.

cURL 
curl -X POST "https://api.aevumnews.com/v2/articles" \

  -H "Authorization: Bearer YOUR_API_KEY" \

  -H "Content-Type: application/json" \

  -d '{

    "title": "New Discovery in Renewable Energy",

    "body": "Researchers at MIT have achieved...",

    "category": "science",

    "tags": ["renewable", "energy", "MIT"],

    "language": "en",

    "image_url": "https://example.com/image.jpg",

    "author": "Dr. Jane Smith",

    "source_url": "https://example.com/original"

  }'
⚠️
Requires Professional or Enterprise tier. Submitted content undergoes editorial review. Response returns 202 Accepted during review period.
GET /v2/categories List all available categories
JSON Response 
{
  "status": "success",
  "categories": [
    {"slug": "world", "name": "World Affairs", "article_count": 24853},
    {"slug": "politics", "name": "Politics", "article_count": 21340},
    {"slug": "technology", "name": "Technology", "article_count": 18762},
    {"slug": "business", "name": "Business & Finance", "article_count": 15234},
    {"slug": "science", "name": "Science", "article_count": 12089},
    {"slug": "culture", "name": "Culture & Arts", "article_count": 9845},
    {"slug": "health", "name": "Health", "article_count": 8621},
    {"slug": "climate", "name": "Climate & Environment", "article_count": 11432}
  ]
}
GET /v2/tags List and filter by tags

Description

Retrieve available tags for filtering. Use ?q= for tag search, ?popular=true for trending tags.

cURL — Trending Tags 
curl "https://api.aevumnews.com/v2/tags?popular=true&limit=10" \

  -H "Authorization: Bearer YOUR_API_KEY"

🔔 Webhooks

Receive real-time notifications when specific events occur. Configure webhook URLs in your dashboard.

article.published

Triggered when a new article is published matching your filter criteria.

article.updated

Triggered when an existing article is updated or corrected.

article.deleted

Triggered when an article is removed from the feed.

breaking_news.alert

Triggered when a breaking news event is declared.

category.trending

Triggered when a category reaches trending status.

rate_limit.warning

Triggered when API usage reaches 80% of your limit.

ℹ️
Webhook Payload: All events deliver a JSON payload with event type, timestamp, and resource data. Verify signatures using the X-Aevum-Signature header.
Webhook Payload Example 
{
  "event": "article.published",
  "timestamp": "2025-01-15T14:32:00Z",
  "data": {
    "id": "art_9yL3nO0qR2,
    "headline": "Global Markets Hit Record Highs",
    "category": "business",
    "region": "global",
    "url": "https://www.aevumnews.com/articles/art_9yL3nO0qR2"
  }
}

📊 Analytics Endpoint

Access aggregated data about your API usage and content performance.

GET /v2/analytics/usage API usage statistics
JSON Response 
{
  "period": {"from": "2025-01-01", "to": "2025-01-15"},
  "total_requests": 45230,
  "articles_fetched": 9046,
  "search_queries": 36184,
  "avg_response_time_ms": 142,
  "error_rate": "0.3%",
  "rate_limit_hits": 12,
  "top_categories": [
    {"category": "technology", "count": 12450},
    {"category": "world", "count": 9870},
    {"category": "business", "count": 7640}
  ]
}

📦 Bulk Operations

Retrieve or process multiple articles efficiently with batch endpoints.

POST /v2/bulk/articles Fetch multiple articles by ID
cURL — Bulk Fetch 
curl -X POST "https://api.aevumnews.com/v2/bulk/articles" \

  -H "Authorization: Bearer YOUR_API_KEY" \

  -H "Content-Type: application/json" \

  -d '{"ids": ["art_8xK2mN9pQ1", "art_7wJ1lM8oP0", "art_6vI0kL7nO9"]}'

📡 Real-Time Streaming

Subscribe to live news feeds via WebSocket or Server-Sent Events.

✅
WebSocket: wss://stream.aevumnews.com/v2
SSE: https://api.aevumnews.com/v2/stream/sse
JavaScript — WebSocket Connection 
const ws = new WebSocket('wss://stream.aevumnews.com/v2');

ws.onopen = () => {
  ws.send(JSON.stringify({
    "action": "subscribe",
    "event": "article.published",
    "filters": {
      "categories": ["technology", "science"],
      "regions": ["US", "UK", "global"]
    }
  }));
};

ws.onmessage = (event) => {
  const article = JSON.parse(event.data);
  console.log(`New: ${article.headline}`);
};

ws.onerror = (error) => console.error('Stream error:', error);

🚨 Error Handling

The API uses standard HTTP status codes and returns structured error responses.

Error Response Format 
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has expired.",
    "status": 401,
    "request_id": "req_9xM3pN2qR5",
    "help": "https://docs.aevumnews.com/errors/invalid_api_key"
  }
}

HTTP Status Codes

200
OK Request succeeded. Returns requested data.
201
Created Resource successfully created.
202
Accepted Request accepted for processing (e.g., article submission review).
400
Bad Request Malformed query parameters or invalid JSON body.
401
Unauthorized Invalid or missing API key. Check your credentials.
403
Forbidden API key lacks permission for this endpoint or tier.
404
Not Found Requested resource does not exist.
429
Rate Limited Too many requests. Check X-RateLimit-Reset header.
500
Server Error Internal server error. Contact support if persistent.

📦 SDKs & Libraries

Official and community-maintained SDKs for your preferred language.

🟨
JavaScript / Node.js

@aevum/sdk-js

🐍
Python

aevum-python

🦀
Rust

aevum-rs

🐹
Go

github.com/aevum/go-sdk

☕
Java

aevum-java-sdk

💎
Ruby

aevum-ruby

JavaScript SDK Usage 
// npm install @aevum/sdk-js

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

const aevum = new AevumClient({
  apiKey: process.env.AEVUM_API_KEY,
  timeout: 5000,
  retries: 3
});

// Fetch latest tech news
const articles = await aevum.news.fetch({
  category: 'technology',
  perPage: 50,
  sort: 'date'
});

// Search for specific topic
const results = await aevum.search.query('quantum computing breakthrough', {
  minDate: '2025-01-01',
  highlight: true
});

// Real-time streaming
const stream = aevum.stream.subscribe({
  events: ['article.published', 'breaking_news.alert'],
  filters: {
    categories: ['technology', 'science'],
    regions: ['global']
  }
});

stream.on('message', (data) => {
  console.log(data.headline);
});

💎 Pricing

Choose the plan that fits your integration needs. All plans include a 14-day free trial.

Starter
Free / forever

Perfect for prototyping and small projects.

  • 1,000 requests / minute
  • Basic news feed access
  • Search with 500 qpd
  • Standard response format
  • Community support
Start Free
Professional
$299 / month

For growing teams and production apps.

  • 10,000 requests / minute
  • All endpoints + streaming
  • Advanced search & filters
  • Webhook subscriptions
  • Syndication submissions
  • Priority email support
  • Analytics dashboard
Start Trial
Enterprise
Custom

For large-scale operations and media partners.

  • 100,000+ requests / minute
  • Unlimited everything
  • Dedicated infrastructure
  • Custom SLA (99.99%)
  • White-label options
  • Dedicated account manager
  • Custom data pipelines
  • On-premise deployment
Contact Sales

❓ Frequently Asked Questions

How do I get an API key? +
Sign up for an enterprise account at portal.aevumnews.com. Your API key is generated instantly in the dashboard under Settings → API Keys. You can generate multiple keys for different environments.
Can I use the API for commercial redistribution? +
Yes. Professional and Enterprise plans include a content redistribution license. Articles may be republished with proper attribution to Aevum News and a link to the original article. Contact sales for white-label arrangements.
What is the data freshness / latency? +
REST API data is updated within 30 seconds of publication. WebSocket streaming delivers real-time push notifications. Enterprise customers on dedicated infrastructure can achieve sub-5-second latency.
Do you support geographic data filtering? +
Absolutely. All endpoints support the region parameter using ISO 3166-1 alpha-2 country codes (e.g., US, GB, JP). You can also filter by multi-region combinations and the special global keyword.
How do I handle rate limiting gracefully? +
Monitor the X-RateLimit-Remaining header in responses. When it approaches zero, implement exponential backoff. Webhook events rate_limit.warning are sent at 80% usage. Enterprise plans can request custom limits or burst allowances.
Is there a sandbox / test environment? +
Yes! Use the sandbox base URL https://sandbox-api.aevumnews.com/v2 with a sandbox key from your dashboard. The sandbox contains synthetic data and unlimited requests for development and testing.