> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# News Intelligence

> AI-powered news monitoring and analysis

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Chat about a story (optional)">
    Use `POST /news/stories/{id}/chat` with a message and persona ID to ask natural-language questions. Consumes credits.
  </Step>
</Steps>

## Key Features

<CardGroup cols={2}>
  <Card title="Trending Stories" icon="fire">
    Real-time trending news across topics
  </Card>

  <Card title="Persona Analysis" icon="user">
    Understand news from different audience perspectives
  </Card>

  <Card title="Story Chat" icon="comments">
    Ask questions about any news story
  </Card>

  <Card title="Personalized Feed" icon="rss">
    News tailored to your interests
  </Card>
</CardGroup>

## Get Trending Stories

Fetch stories by topic. Listing stories is low-cost; analysis and chat consume credits.

<CodeGroup>
  ```python Python theme={"dark"}
  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']}")
  ```

  ```javascript JavaScript theme={"dark"}
  const resp = await fetch(
    "https://app.mavera.io/api/v1/news/stories/trending?topics=technology,ai&limit=10",
    { headers: { Authorization: "Bearer mvra_live_your_key_here" } }
  );
  const data = await resp.json();
  if (data.error) throw new Error(data.error.message);
  data.data.forEach((s) => console.log(s.title, s.source, s.published_at));
  ```
</CodeGroup>

## Analyze a Story

Get AI analysis of a story from multiple persona perspectives. Each perspective includes sentiment and key takeaway.

<CodeGroup>
  ```python Python theme={"dark"}
  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')}")
  ```

  ```javascript JavaScript theme={"dark"}
  const resp = await fetch(
    `https://app.mavera.io/api/v1/news/stories/${storyId}/analyze`,
    {
      method: "POST",
      headers: {
        Authorization: "Bearer mvra_live_your_key_here",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        persona_ids: [genZId, b2bId],
      }),
    }
  );
  const analysis = await resp.json();
  analysis.perspectives?.forEach((p) => {
    console.log(`${p.persona_name}: ${p.sentiment} - ${p.key_takeaway}`);
  });
  ```
</CodeGroup>

## 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?"

<CodeGroup>
  ```python Python theme={"dark"}
  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", ""))
  ```

  ```javascript JavaScript theme={"dark"}
  const resp = await fetch(
    `https://app.mavera.io/api/v1/news/stories/${storyId}/chat`,
    {
      method: "POST",
      headers: {
        Authorization: "Bearer mvra_live_your_key_here",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        message: "How might this news affect consumer behavior?",
        persona_id: millennialId,
      }),
    }
  );
  const data = await resp.json();
  if (!data.error) console.log(data.content);
  ```
</CodeGroup>

## Personalized Feed

Get a feed tailored to your topics of interest.

<CodeGroup>
  ```python Python theme={"dark"}
  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", [])
  ```

  ```javascript JavaScript theme={"dark"}
  const resp = await fetch(
    "https://app.mavera.io/api/v1/news/stories/personalized?topics=marketing,ecommerce&limit=20",
    { headers: { Authorization: "Bearer mvra_live_your_key_here" } }
  );
  const { data: stories } = await resp.json();
  ```
</CodeGroup>

## Credit Costs

| Endpoint                          | Typical Cost            |
| --------------------------------- | ----------------------- |
| `GET /news/stories/trending`      | 0 (or minimal)          |
| `GET /news/stories/personalized`  | 0 (or minimal)          |
| `POST /news/stories/{id}/analyze` | 5–20 credits            |
| `POST /news/stories/{id}/chat`    | 1–5 credits per message |

Cost depends on analysis depth and persona count. See [Credits](/guides/credits) for your plan allocation.

## Best Practices

<AccordionGroup>
  <Accordion title="Choose personas by audience">
    Use Gen Z / Millennial personas for consumer-focused stories; B2B / Expert personas for industry and market stories.
  </Accordion>

  <Accordion title="Cache trending stories">
    Trending and personalized feeds change over time, but you can cache for a few minutes to reduce API calls.
  </Accordion>

  <Accordion title="Batch analysis">
    If analyzing many stories, space requests to respect [rate limits](/guides/rate-limits).
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Credits" icon="coins" href="/guides/credits">
    News analysis costs vary by story count
  </Card>

  <Card title="Personas" icon="user" href="/features/personas">
    Persona analysis for personalized feeds
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/guides/rate-limits">
    Batch analysis within limits
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/news/get-trending-news-stories">
    Full API specification
  </Card>
</CardGroup>