Aevum News API

📋 Overview

The Aevum News API provides programmatic access to our global news database. Retrieve articles, search across categories, manage subscriptions, and integrate real-time news feeds into your applications.

2.5M+

Articles

120+

Countries

50+

🌐 Base URL

All API requests are made to the base URL below. Replace YOUR_API_KEY with your actual API key.

Production

https://api.aevumnews.com/v2/ Hide

Sandbox (Testing)

https://sandbox-api.aevumnews.com/v2/ Hide

🔑 Authentication

Aevum News API uses API key authentication. Include your API key in the request header with every call. You can generate and manage your API keys from the Developer Dashboard.

How to authenticate

Include the Authorization header with your API key in every request:

                                HTTP Headers
                                
Authorization: Bearer aev_live_sk_8x9fK2mN7pQ4wR6tY1zA3bC5dE0gH9jL

Content-Type: application/json

X-Api-Version: 2025-01-15

API Key Types

                            Key Format
                            
                        
/* Live / Production key */
aev_live_sk_{base64-encoded-key}

/* Sandbox / Test key */
aev_test_sk_{base64-encoded-key}

/* Read-only key */
aev_ro_sk_{base64-encoded-key}

⚠️

Keep your API key secret. Never expose it in client-side code, public repositories, or browser-accessible files. Use environment variables to store your keys securely.

⚡ Rate Limiting

API requests are rate-limited to ensure fair usage and platform stability. Limits vary by subscription tier. Rate limit headers are included in every response.

Rate Limits by Tier

Choose a plan that fits your needs at aevumnews.com/pricing

100

Requests / Minute

Free

1,000

Requests / Minute

Pro

10,000

Requests / Minute

Enterprise

                            Response Headers
                            
                        
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1704067200
Retry-After: 42 /* Only on 429 responses */

⚠️ Error Handling

The API uses standard HTTP status codes to indicate success or failure. Error responses include a structured JSON body with details about what went wrong.

                            Error Response Format
                            
                        
{
  "error": {
    "code": "invalid_request",
    "message": "The 'q' parameter is required for search",
    "type": "bad_request",
    "details": {
      "field": "q",
      "reason": "missing_parameter"
    }
  }
}

HTTP Status Codes

Status	Meaning	Description
200	OK	Request succeeded. Response body contains the data.
201	Created	Resource was successfully created.
400	Bad Request	Malformed request. Check the error details for the issue.
401	Unauthorized	Invalid or missing API key.
403	Forbidden	API key lacks permission for this resource.
404	Not Found	Requested resource does not exist.
429	Too Many Requests	Rate limit exceeded. Wait and retry after `Retry-After` seconds.
500	Server Error	Internal server error. Contact support if persistent.
503	Service Unavailable	API is temporarily unavailable. Check status page.

📰 Articles

Access and retrieve articles from Aevum News' global journalism database. Supports filtering by category, tags, date range, language, and more.

GET

/articles

● Stable

Retrieve a paginated list of articles. Supports filtering by category, tags, author, date range, language, and region. Results are sorted by publish date (newest first) by default.

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number (default: 1)
per_page	integer	Optional	Results per page (1-100, default: 20)
category	string	Optional	Filter by category slug (e.g., "world", "tech")
tags	string	Optional	Comma-separated tags (e.g., "climate,AI")
author	string	Optional	Filter by author slug or ID
language	string	Optional	ISO 639-1 language code (default: "en")
region	string	Optional	ISO 3166-1 region code (e.g., "US", "GB", "IN")
from_date	string	Optional	ISO 8601 date (e.g., "2025-01-01")
to_date	string	Optional	ISO 8601 date (e.g., "2025-01-31")
sort_by	string	Optional	"date", "relevance", "popularity" (default: "date")
status	string	Optional	"published", "draft", "archived" (default: "published")
featured	boolean	Optional	Filter for featured articles only

Example Response

{
  "status": "success",
  "data": {
    "articles": [
      {
        "id": "art_9xK2mN7pQ4wR",
        "title": "Global Climate Summit",
        "slug": "global-climate-summit-2025",
        "summary": "World leaders convene...",
        "category": "world",
        "author": {
          "id": "usr_eR5tY1zA3bC5",
          "name": "Elena Rodriguez",
          "slug": "elena-rodriguez"
        },
        "published_at": "2025-01-14T08:30:00Z",
        "updated_at": "2025-01-14T09:15:00Z",
        "featured_image": "https://cdn.aevumnews.com/...",
        "read_time": 8,
        "views": 142530,
        "tags": ["climate", "summit", "global"]
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 2847,
      "total_pages": 143,
      "next": "/articles?page=2",
      "prev": null
    }
  }
}

GET

/articles/:id

● Stable

Retrieve a single article by its ID or slug. Returns full content, metadata, author info, and related articles.

Path Parameters

Parameter	Type	Required	Description
id	string	Required	Article ID (e.g., "art_9xK2mN7pQ4wR") or slug (e.g., "global-climate-summit-2025")

Response Includes

Full article body, featured image (multiple resolutions), author profile with social links, category & tag objects, reading progress metrics, related articles (up to 5), and content formatting (HTML + markdown).

POST

/articles

New

Create a new article draft or publish it directly. Requires write scope API key.

Request Body

{
  "title": "Breaking: Major Policy Shift",
  "slug": "major-policy-shift-2025",
  "category": "politics",
  "tags": ["policy", "reform"],
  "body": "Full article content in markdown...",
  "summary": "Brief 2-sentence summary...",
  "featured_image": "https://cdn.example.com/img.jpg",
  "status": "draft",
  "language": "en",
  "region": "US"
}

Response

{
  "status": "success",
  "data": {
    "article": {
      "id": "art_2bC5dE0gH9jL",
      "status": "draft",
      "created_at": "2025-01-15T12:00:00Z"
    }
  }
}

✅

New Feature: The create article endpoint now supports AI-assisted drafting. Pass "auto_expand": true to generate an expanded outline from your brief.

🔍 Search

Full-text search across all published articles with advanced filtering, typo tolerance, and relevance scoring.

GET

/search

● Stable

Search articles by keyword, phrase, or advanced query syntax. Supports boolean operators, field-specific search, and proximity queries.

Query Parameters

Parameter	Type	Required	Description
q	string	Required	Search query (supports boolean operators)
fields	string	Optional	Comma-separated fields: "title,body,summary,author"
fuzziness	string	Optional	Typo tolerance: "auto", "1", "2" (default: "auto")
highlight	boolean	Optional	Return highlighted matches (default: false)
min_relevance	number	Optional	Minimum relevance score 0-1 (default: 0.0)
locale	string	Optional	Search locale for language-specific processing

Search Syntax Examples

/* Basic search */
/search?q=climate+change

/* Boolean search */
/search?q=(AI+OR+machine+learning)+AND+healthcare

/* Field-specific */
/search?q=title:inflation+AND+body:economy

/* Phrase match */
/search?q=\"sustainable development goals\"

/* Proximity */
/search?q=quantum~3+computing

📡 Live Feed

Real-time news streaming via Server-Sent Events (SSE) or WebSocket connections. Get breaking news as it happens.

GET

/feed/live

● Beta

Establish a real-time connection to receive live news updates. Supports filtering by category, priority level, and region.

                                SSE Connection
                                
                            
const source = new EventSource(
  "https://api.aevumnews.com/v2/feed/live?categories=world,tech&priority=critical",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

source.addEventListener("news_event", (event) => {
  const article = JSON.parse(event.data);
  console.log(article.title);
});

🔥 Trending

Access trending topics, hot articles, and rising stories based on real-time engagement metrics.

GET

/trending

● Stable

Returns trending articles and topics. Supports time window filtering.

Query Parameters

Parameter	Type	Required	Description
time_window	string	Optional	"hour", "6h", "24h", "7d" (default: "24h")
limit	integer	Optional	Number of results (default: 10, max: 50)
region	string	Optional	Region for localized trending

Example Response

{
  "status": "success",
  "data": {
    "trending_topics": [
      { "topic": "AI Regulation", "mentions": 12847, "velocity": "▲ 340%" }
    ],
    "trending_articles": [
      { "id": "art_...", "title": "...", "views": 524100 }
    ]
  }
}

🏷️ Categories

Retrieve all available content categories with metadata, article counts, and hierarchy information.

GET

/categories

● Stable

Returns all categories. Use ?parent=none for top-level only.

#️⃣ Tags

Query tags for article classification and filtering.

GET

/tags

● Stable

List all tags. Parameters: ?q=climate to search, ?limit=50.

🖼️ Media Library

Access and upload media assets for your articles.

GET

/media

● Stable

List media assets. Supports filtering by type, date, and collection.

POST

/media/upload

● Stable

Upload images, videos, or documents. Max file size: 25MB. Supported formats: JPEG, PNG, WebP, MP4, PDF.

✍️ Writers

Access journalist profiles, portfolios, and contact information.

GET

/writers

● Stable

List all writers. Parameters: ?q=name to search, ?specialization=tech.

GET

/writers/:id

● Stable

Get writer profile including bio, photo, social links, and article portfolio.

👤 Users

Manage user accounts, profiles, and preferences.

GET

/users/me

● Stable

Returns the authenticated user's profile and subscription details.

PUT

/users/me/preferences

● Stable

Update user preferences: newsletter settings, notification channels, and content filters.

📌 Subscriptions

Manage user subscriptions to categories, tags, and authors.

GET

/subscriptions

● Stable

List all active subscriptions for the authenticated user.

POST

/subscriptions

● Stable

Subscribe to a category, tag, or author. Request body: {"type": "category", "target_id": "cat_tech"}.

DELETE

/subscriptions/:id

● Stable

Unsubscribe from a category, tag, or author.

🔖 Bookmarks

Save and organize article bookmarks for later reading.

GET

/bookmarks

● Stable

List bookmarked articles. Parameters: ?collection=default.

POST

/bookmarks

● Stable

Bookmark an article. Request body: {"article_id": "art_xxx", "collection": "default"}.

🪝 Webhooks

Receive real-time notifications for events. Configure webhook endpoints from your dashboard or the API.

GET

/webhooks

● Stable

List all configured webhooks for your account.

Available Events

article.published Triggered when a new article is published

article.updated Triggered when an article is modified

trending.reached Triggered when an article enters trending

subscription.created Triggered on new subscription

breaking.news Triggered for breaking news alerts

ℹ️

Verification: All webhook payloads include an X-Aevum-Signature header. Verify using your webhook secret to ensure authenticity.

📦 SDKs & Libraries

Official SDKs for popular languages. Community SDKs are also available.

🟨

JavaScript

v2.4.0

🐍

Python

v2.4.0

🔵

Go

v2.3.1

💎

Ruby

v2.4.0

☕

Java

v2.3.0

🐹

Go

v2.2.4

                            Python Quick Start
                            
                        
import aevumnews

client = aevumnews.Client(
    api_key="aev_live_sk_xxxx",
    base_url="https://api.aevumnews.com/v2"
)

# Fetch articles
articles = client.articles.list(
    category="tech",
    per_page=10,
    sort_by="date"
)

for article in articles.data:
    print(article.title)

# Search
results = client.search.execute(
    q="AI regulation",
    fuzziness="auto"
)

🧪 Sandbox Environment

Test the API in our sandbox environment with sample data. No production data is affected.

✅

Sandbox Benefits: Pre-loaded with sample articles, users, and categories. Use your aev_test_sk_... key to connect to sandbox-api.aevumnews.com.

Sandbox Base URL

https://sandbox-api.aevumnews.com/v2/

📝 Changelog

January 15, 2025

v2.4.0 — Live Feed & Article Creation

Added real-time live feed endpoint (SSE). New article creation endpoint with AI-assisted drafting. Enhanced search with proximity queries and field-specific search.

December 1, 2024

v2.3.0 — Enhanced Search & SDK Updates

Improved search relevance scoring by 40%. Added Go and Java SDKs. New trending endpoint with real-time velocity tracking.

October 15, 2024

v2.2.0 — Webhooks & Media Library

Added webhook support for event-driven integration. Media library endpoint with upload capabilities. Writer profiles with portfolio data.

September 1, 2024

v2.1.0 — Categories, Tags & User APIs

Category and tag query endpoints. User management and subscription APIs. Bookmark management. Rate limit increases for Pro and Enterprise tiers.

June 15, 2024

v2.0.0 — Major API Redesign

Complete RESTful redesign. New authentication system. Pagination, filtering, and sorting across all endpoints. Breaking changes from v1.x.

🟢 API Status

View real-time system status and incident history.

✅

All Systems Operational

Last updated: 2 minutes ago

● API Gateway

99.99% uptime (30d)

● Search Engine

99.97% uptime (30d)

● Live Feed

99.95% uptime (30d)

● CDN

99.99% uptime (30d)

View Full Status Page →

💬 Support

💬

Need help? Contact our developer support team at api-support@aevumnews.com or join our Discord community for real-time assistance.

📧

Email

api-support@aevumnews.com

💬

Discord

discord.gg/aevumdevs

🐛

GitHub Issues

github.com/aevum/api/issues

Aevum NewsAPI Documentation

📋 Overview

🌐 Base URL

🔑 Authentication

API Key Types

⚡ Rate Limiting

Rate Limits by Tier

⚠️ Error Handling

HTTP Status Codes

📰 Articles

/articles

/articles/:id

/articles

🔍 Search

/search

📡 Live Feed

/feed/live

🔥 Trending

/trending

🏷️ Categories

/categories

#️⃣ Tags

/tags

🖼️ Media Library

/media

/media/upload

✍️ Writers

/writers

/writers/:id

👤 Users

/users/me

/users/me/preferences

📌 Subscriptions

/subscriptions

/subscriptions

/subscriptions/:id

🔖 Bookmarks

/bookmarks

/bookmarks

🪝 Webhooks

/webhooks

Available Events

📦 SDKs & Libraries

🧪 Sandbox Environment

📝 Changelog

🟢 API Status

💬 Support

Aevum News
API Documentation