Skip to main content

​
Overview

The News API provides AI-powered news intelligence — trending stories, persona-based analysis, and scheduled digests. Stay informed about industry trends and understand how different audiences perceive news events.

​
Typical Flow

1

Get trending or personalized stories

Use GET /news/stories/trending or GET /news/stories/personalized with topics and limit. Returns story IDs, titles, sources, and published dates.
2

Analyze a story (optional)

Use POST /news/stories/{id}/analyze with persona IDs to get sentiment and key takeaways from different audience perspectives. Consumes credits.
3

Chat about a story (optional)

Use POST /news/stories/{id}/chat with a message and persona ID to ask natural-language questions. Consumes credits.

​
Key Features

Trending Stories

Real-time trending news across topics

Persona Analysis

Understand news from different audience perspectives

Story Chat

Ask questions about any news story

Personalized Feed

News tailored to your interests
Fetch stories by topic. Listing stories is low-cost; analysis and chat consume credits. 
import requests

response = requests.get(
    "https://app.mavera.io/api/v1/news/stories/trending",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    params={"topics": "technology,ai", "limit": 10}
)

data = response.json()
if "error" in data:
    raise Exception(data["error"]["message"])

stories = data["data"]
for story in stories:
    print(f"{story['title']}")
    print(f"  ID: {story['id']}")
    print(f"  Source: {story['source']}")
    print(f"  Published: {story['published_at']}")

​
Analyze a Story

Get AI analysis of a story from multiple persona perspectives. Each perspective includes sentiment and key takeaway. 
response = requests.post(
    f"https://app.mavera.io/api/v1/news/stories/{story_id}/analyze",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={"persona_ids": ["gen_z_consumer_id", "b2b_executive_id"]}
)

analysis = response.json()
if "error" in analysis:
    raise Exception(analysis["error"]["message"])

for perspective in analysis["perspectives"]:
    print(f"{perspective['persona_name']}:")
    print(f"  Sentiment: {perspective['sentiment']}")
    print(f"  Key Takeaway: {perspective['key_takeaway']}")

print(f"Credits used: {analysis.get('usage', {}).get('credits_used')}")

​
Chat About a Story

Ask natural-language questions about a story with a persona lens. Use for “How might this affect X?” or “What would Y think about this?” 
response = requests.post(
    f"https://app.mavera.io/api/v1/news/stories/{story_id}/chat",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "message": "How might this news affect consumer behavior?",
        "persona_id": "millennial_consumer_id"
    }
)

data = response.json()
if "error" not in data:
    print(data.get("content", ""))

​
Personalized Feed

Get a feed tailored to your topics of interest. 
response = requests.get(
    "https://app.mavera.io/api/v1/news/stories/personalized",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    params={"topics": "marketing,ecommerce", "limit": 20}
)
stories = response.json().get("data", [])

​
Credit Costs

EndpointTypical Cost
GET /news/stories/trending0 (or minimal)
GET /news/stories/personalized0 (or minimal)
POST /news/stories/{id}/analyze5–20 credits
POST /news/stories/{id}/chat1–5 credits per message
Cost depends on analysis depth and persona count. See Credits for your plan allocation.

​
Best Practices

Use Gen Z / Millennial personas for consumer-focused stories; B2B / Expert personas for industry and market stories.
If analyzing many stories, space requests to respect rate limits.

Credits

News analysis costs vary by story count

Personas

Persona analysis for personalized feeds

Rate Limits

Batch analysis within limits

API Reference

Full API specification