Aevum News API Reference

Integrate Aevum News into your applications. Our RESTful API provides comprehensive access to articles, stories, authors, categories, analytics, and more. Build real-time news dashboards, content aggregators, and automated journalism workflows.

Base URL

https://api.aevumnews.com/v2

ℹ️

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. The API uses OAuth 2.0 for authentication.

Authentication

Aevum News API supports three authentication methods depending on your use case.

API Key (Simple)

Include your API key in the request header. Best for server-to-server communication and read-only access.

Header
Authorization: Bearer YOUR_API_KEY

OAuth 2.0 (Full)

For write operations and user-specific data. Requires a registered application and redirect URI.

Request
GET https://api.aevumnews.com/oauth/authorize
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=https://yourapp.com/callback
&scope=read write admin

Webhook Signature

Verify webhook payloads using HMAC-SHA256. The signature is sent in the Aevum-Signature header.

Header
Aevum-Signature: t=1698765432,v1=a1b2c3d4e5...

Rate Limiting

API requests are rate-limited based on your subscription tier. Exceeded limits return a 429 Too Many Requests status.

Free

100

requests / hour

Pro

5,000

requests / hour

Enterprise

Unlimited

with fair use

ℹ️

Current rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Error Handling

The API uses conventional HTTP response codes. Errors are returned in a standardized JSON format.

JSON — Error Response
{
  "error": {
    "code": "invalid_request",
    "message": "The 'q' parameter is required for search endpoints.",
    "status": 400,
    "documentation_url": "https://docs.aevumnews.com/errors#invalid_request"
  }
}

HTTP Code	Error	Description
400	`bad_request`	Malformed request or missing required parameters.
401	`unauthorized`	Missing or invalid authentication credentials.
403	`forbidden`	Insufficient permissions for the requested resource.
404	`not_found`	The requested resource does not exist.
429	`rate_limited`	Too many requests. Retry after `X-RateLimit-Reset`.
500	`internal_error`	Server error. If persistent, contact support.
502	`bad_gateway`	Upstream service unavailable.
503	`unavailable`	Service temporarily down for maintenance.

Pagination

All list endpoints support cursor-based pagination for consistent performance with large datasets.

Parameter	Type	Required	Default	Description
page	integer	Optional	1	Page number for offset-based pagination.
per_page	integer	Optional	20	Number of items per page (max 100).
cursor	string	Optional	—	Cursor for next/previous page navigation.
sort	string	Optional	created_at	Sort field: `created_at`, `updated_at`, `relevance`.
order	string	Optional	desc	Sort order: `asc` or `desc`.

JSON — Paginated Response
{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_items": 1847,
    "total_pages": 93,
    "has_next": true,
    "has_prev": false,
    "next_cursor": "eyJpZCI6MTIzLCJjdXJzb3IiOiIyMDI1LTAxLTE1In0=",
    "prev_cursor": null
  }
}

Articles

Read and manage Aevum News articles. Articles are the core content objects in our system.

GET /articles List all articles

Request

Response 200

Response 4xx

Query Parameters

Parameter	Type	Required	Description
category	string	Optional	Filter by category slug (e.g., `politics`, `tech`).
author_id	string	Optional	Filter by author UUID.
tag	string	Optional	Filter by tag slug. Can be repeated.
status	string	Optional	Filter by status: `published`, `draft`, `archived`.
published_after	datetime	Optional	ISO 8601 timestamp. Inclusive.
published_before	datetime	Optional	ISO 8601 timestamp. Inclusive.
language	string	Optional	ISO 639-1 language code. Default: `en`.
featured	boolean	Optional	Only return featured articles. Default: `false`.

Example Request

cURL
curl https://api.aevumnews.com/v2/articles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "technology",
    "featured": true,
    "per_page": 10,
    "sort": "relevance",
    "order": "desc"
  }'

Success Response

200 OK

Returns a paginated array of article objects.

JSON
{
  "data": [
    {
      "id": "art_9f8e7d6c5b4a3210",
      "title": "Global Markets Reach All-Time High Amid Tech Rally",
      "slug": "global-markets-tech-rally",
      "summary": "Major indices surge as technology sector reports record earnings.",
      "content": "Full article content in markdown format...",
      "author": {
        "id": "aut_a1b2c3d4e5f6",
        "name": "Elena Rodriguez",
        "slug": "elena-rodriguez"
      },
      "category": {
        "id": "cat_biz_finance",
        "name": "Business & Finance",
        "slug": "business"
      },
      "tags": ["markets", "tech", "earnings"],
      "featured": true,
      "language": "en",
      "reading_time": 8,
      "status": "published",
      "views": 48293,
      "created_at": "2025-01-15T09:30:00Z",
      "updated_at": "2025-01-15T11:45:00Z",
      "published_at": "2025-01-15T10:00:00Z",
      "cover_image": "https://cdn.aevumnews.com/images/abc123.jpg"
    }
  ],
  "pagination": { ... }
}

Error Responses

401 Unauthorized

Missing or invalid API key.

422 Unprocessable

Invalid query parameter format.

GET /articles/:id Retrieve a single article

Request

Response 200

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The article's unique UUID.

Query Parameters

Parameter	Type	Required	Description
include	string	Optional	Comma-separated: `author,category,comments,related`.
format	string	Optional	Output format: `json` or `markdown`. Default: `json`.

cURL
curl https://api.aevumnews.com/v2/articles/art_9f8e7d6c5b4a3210 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "include": "author,category,related" }'

200 OK

Returns a single article object with expanded relations.

JSON
{
  "data": {
    "id": "art_9f8e7d6c5b4a3210",
    "title": "Global Markets Reach All-Time High Amid Tech Rally",
    "slug": "global-markets-tech-rally",
    "summary": "Major indices surge as technology sector reports record earnings.",
    "content": "Full article content in markdown format...",
    "author": { /* expanded author object */ },
    "category": { /* expanded category object */ },
    "related": [ /* array of related article IDs */ ],
    "created_at": "2025-01-15T09:30:00Z",
    "published_at": "2025-01-15T10:00:00Z"
  }
}

POST /articles Create a new article

⚠️

This endpoint requires write scope. Only Pro and Enterprise tiers can create articles.

Request

Response 201

Request Body

JSON
{
  "title": "Your Article Title",
  "slug": "your-article-slug",
  "summary": "A brief summary of the article.",
  "content": "Article content in markdown format.",
  "category_id": "cat_biz_finance",
  "author_id": "aut_a1b2c3d4e5f6",
  "tags": ["markets", "tech"],
  "status": "draft",
  "featured": false,
  "cover_image_url": "https://example.com/image.jpg",
  "language": "en"
}

201 Created

Article created successfully.

JSON
{
  "data": {
    "id": "art_new1234567890",
    "title": "Your Article Title",
    "slug": "your-article-slug",
    "status": "draft",
    "created_at": "2025-01-15T14:22:00Z"
  }
}

PUT /articles/:id Update an article

Request

Response 200

Accepts the same body as POST /articles. All fields are optional — only provided fields will be updated.

200 OK

Returns the updated article object.

DELETE /articles/:id Delete an article

Request

Response 204

🚨

Destructive action. This permanently deletes the article and all associated metadata. No undo.

cURL
curl -X DELETE https://api.aevumnews.com/v2/articles/art_9f8e7d6c5b4a3210 \
  -H "Authorization: Bearer YOUR_API_KEY"

204 No Content

Article deleted successfully. No response body.

Stories

Stories are long-form investigative pieces or serialized content that span multiple articles.

GET /stories List all stories

Request

Response 200

Query Parameters

Parameter	Type	Required	Description
status	string	Optional	`published`, `in_progress`, `draft`.
series	string	Optional	Filter by series slug.
completed	boolean	Optional	Only completed stories.

200 OK

Returns a paginated array of story objects with chapter lists.

JSON
{
  "data": [
    {
      "id": "st_abc123def456",
      "title": "The Future of AI in Journalism",
      "series": "ai-journalism-2025",
      "status": "in_progress",
      "total_chapters": 5,
      "published_chapters": 3,
      "authors": ["aut_001", "aut_002"],
      "created_at": "2025-01-10T08:00:00Z"
    }
  ]
}

Authors

GET /authors List all authors

Request

Response 200

Parameter	Type	Required	Description
department	string	Optional	Filter by department: `politics`, `tech`, `world`, etc.
active	boolean	Optional	Only active authors. Default: `true`.

200 OK

Returns paginated author list.

JSON
{
  "data": [
    {
      "id": "aut_a1b2c3d4e5f6",
      "name": "Elena Rodriguez",
      "slug": "elena-rodriguez",
      "bio": "Senior correspondent covering global economics.",
      "department": "politics",
      "article_count": 342,
      "avatar_url": "https://cdn.aevumnews.com/avatars/elena.jpg",
      "twitter": "@elena_reports",
      "active": true
    }
  ]
}

Search

Full-text search across all articles, stories, and authors with advanced filtering.

GET /search Search content

⚠️

The q parameter is required. Searches use Aevum's proprietary relevance engine optimized for news content.

Parameter	Type	Required	Description
q	string	Required	Search query string (min 2 characters).
type	string	Optional	Content type: `articles`, `stories`, `authors`, `all`.
lang	string	Optional	Language filter. Default: `en`.
date_range	string	Optional	`day`, `week`, `month`, `year`, `all`.
sort	string	Optional	`relevance` (default), `date`, `popularity`.

cURL
curl -G --data-urlencode "q=artificial intelligence regulation" \
  --data-urlencode "type=articles" \
  --data-urlencode "date_range=week" \
  --data-urlencode "sort=relevance" \
  https://api.aevumnews.com/v2/search \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON — Response
{
  "data": {
    "results": [
      {
        "type": "article",
        "id": "art_xxx",
        "title": "EU Passes Landmark AI Regulation Act",
        "score": 0.97,
        "highlight": "...comprehensive framework for artificial intelligence governance...",
        "published_at": "2025-01-14T12:00:00Z"
      }
    ],
    "total_results": 847,
    "took_ms": 23,
    "query": "artificial intelligence regulation"
  }
}

Analytics

Access detailed metrics about your content performance, audience engagement, and content trends.

GET /analytics/overview Content performance overview

Parameter	Type	Required	Description
from	datetime	Required	Start date (ISO 8601).
to	datetime	Required	End date (ISO 8601).
granularity	string	Optional	`hourly`, `daily`, `weekly`, `monthly`. Default: `daily`.

JSON — Response
{
  "data": {
    "period": { "from": "2025-01-01T00:00:00Z", "to": "2025-01-31T23:59:59Z" },
    "summary": {
      "total_views": 2847593,
      "total_reads": 1923847,
      "avg_read_time": 4.2,
      "engagement_rate": 0.675,
      "top_article": { "id": "art_top1", "views": 142380 },
      "articles_published": 847,
      "articles_trending": 23
    },
    "daily": [
      { "date": "2025-01-15", "views": 89234, "reads": 61234 },
      { "date": "2025-01-14", "views": 91020, "reads": 62800 }
    ]
  }
}

Subscriptions

GET /subscriptions List user subscriptions

JSON — Response
{
  "data": [
    {
      "id": "sub_xxxxxxxxx",
      "type": "newsletter",
      "frequency": "daily",
      "categories": ["tech", "science"],
      "email": "user@example.com",
      "active": true,
      "created_at": "2024-11-20T10:00:00Z"
    }
  ]
}

Webhooks

Subscribe to real-time event notifications. Aevum News will POST to your configured endpoint when events occur.

Webhook Events

article.published Triggered when a new article is published.

article.updated Triggered when an article is modified.

article.deleted Triggered when an article is deleted.

story.completed Triggered when a story reaches all chapters.

trending.article Triggered when an article enters the trending feed.

subscription.created Triggered when a new subscription is created.

analytics.milestone Triggered when content hits view milestones (1K, 10K, 100K, 1M).

Webhook Setup

JSON — Register Webhook
curl -X POST https://api.aevumnews.com/v2/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook/aevum",
    "events": ["article.published", "article.updated", "trending.article"],
    "secret": "whsec_your_secret_key"
  }'

ℹ️

Webhook payloads are signed with your secret. Verify the signature using the Aevum-Signature header and HMAC-SHA256 with your secret key. Payloads expire after 24 hours.

SDKs & Libraries

Official and community-maintained SDKs for popular languages.

Language	Package	Version	Link
Python	`aevum-news-python`	3.2.1	GitHub →
JavaScript	`@aevum/news-sdk`	4.1.0	npm →
Go	`github.com/aevum/news-go`	2.0.3	GitHub →
Ruby	`aevum_news`	1.8.0	RubyGems →
Rust	`aevum-news`	0.9.5	crates.io →
PHP	`aevum/news-sdk`	2.3.0	Packagist →

Quick Example (JavaScript)

JavaScript
import { AevumClient } from "@aevum/news-sdk";

const aevum = new AevumClient({
  apiKey: "YOUR_API_KEY",
  timeout: 10000
});

// Search for articles
const results = await aevum.search({
  q: "climate change",
  type: "articles",
  dateRange: "week",
});

console.log(results.data.results); // → Array of matched articles

// Get article details
const article = await aevum.articles.getById("art_9f8e7d6c", {
  include: ["author", "category"]
});

// Subscribe to webhooks
await aevum.webhooks.subscribe({
  url: "https://myapp.com/webhook",
  events: ["article.published"]
});

Changelog

v2.4.1

Jan 15, 2025

Latest

✅ Added analytics/audience endpoint with geographic breakdown
✅ Added language filter to search endpoint
✅ Fixed pagination cursor encoding for non-ASCII characters

v2.3.0

Dec 1, 2024

✅ New /stories endpoints for serialized content
✅ Webhook event analytics.milestone added
✅ Rate limit increase: Free tier from 50 → 100 req/hr

v2.0.0

Jun 15, 2024

Breaking

🔴 API v1 deprecated — all routes prefixed with /v2
🔴 OAuth 1.0 replaced with OAuth 2.0
🔴 UUID identifiers replace numeric IDs
✅ Cursor-based pagination replaces offset pagination

Support

Need help? Our developer support team is here to assist you.

📧 Email Support

For technical questions and API issues.

api-support@aevumnews.com

💬 Community Forum

Ask questions and share solutions with other developers.

community.aevumnews.com

🐛 Bug Reports

Found a bug? Report it through our issue tracker.

github.com/aevum/api/issues

Aevum News API Reference

Authentication

API Key (Simple)

OAuth 2.0 (Full)

Webhook Signature

Rate Limiting

Error Handling

Pagination

Articles

Query Parameters

Example Request

Path Parameters

Query Parameters

Request Body

Stories

Query Parameters

Authors

Categories

Search

Analytics

Subscriptions

Webhooks

SDKs & Libraries

Changelog

Support

📧 Email Support

💬 Community Forum

🐛 Bug Reports