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

# Perigon

> 4 production-ready jobs — story clustering for content calendars, entity-based competitive intelligence, AI summary news digests with personas, and geographic news for market-specific messaging

Perigon is a full-stack news intelligence API that goes beyond raw articles — it provides clustered stories, entity extraction, AI summaries, and geographic tagging out of the box. These four jobs leverage Perigon's structured news data with Mavera's surfaces (Mave Agent, Personas, Focus Groups, Generate) to build content calendars from story clusters, extract entity-level competitive intelligence, create persona-voiced news digests, and localize messaging by geography.

***

## API Reference Card

| Detail            | Value                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------- |
| **Base URL**      | `https://api.goperigon.com/v1/`                                                        |
| **Auth**          | API key via `apiKey` query param, `x-api-key` header, or `Authorization: Bearer {key}` |
| **Rate limits**   | Plan-dependent (Starter: 100 req/day, Pro: 10K/day, Enterprise: custom)                |
| **Key endpoints** | `/all`, `/stories/all`, `/people/all`, `/sources/all`                                  |
| **Mavera base**   | `https://app.mavera.io/api/v1`                                                         |
| **Mavera auth**   | `Authorization: Bearer mvra_live_...`                                                  |

<Info>
  All examples use `PERIGON_API_KEY` for Perigon and `MAVERA_API_KEY` for Mavera. Perigon supports three auth methods — examples use the `apiKey` query parameter for simplicity. Switch to header-based auth for production.
</Info>

***

## Prerequisites

<Steps>
  <Step title="Perigon API key">Sign up at [goperigon.com](https://www.goperigon.com/) and copy your API key from the dashboard.</Step>
  <Step title="Choose your plan">Starter (100 req/day) is sufficient for testing. Pro and Enterprise plans unlock stories clustering, entity endpoints, and higher throughput.</Step>
  <Step title="Mavera API key">Get your key from [Mavera dashboard](https://app.mavera.io/settings/api-keys).</Step>

  <Step title="Environment variables">
    ```bash theme={"dark"}
    export PERIGON_API_KEY="your-perigon-key"
    export MAVERA_API_KEY="mvra_live_xxxxx"
    ```
  </Step>
</Steps>

***

## Jobs

| # | Job                                                                        | Perigon Data          | Mavera Surface          | Output                           |
| - | -------------------------------------------------------------------------- | --------------------- | ----------------------- | -------------------------------- |
| 1 | [Story Clustering → Content Calendar](story-clustering-calendar)           | /stories/all          | Mave Agent + Generate   | Themed content calendar          |
| 2 | [Entity-Based Competitive Intelligence](entity-competitive-intelligence)   | /all (entity filter)  | Mave Agent (Chat)       | Entity-level competitor analysis |
| 3 | [AI Summary → News Digest with Personas](ai-summary-persona-digest)        | /all (with summaries) | Personas + Speak        | Persona-voiced weekly digest     |
| 4 | [Geographic News → Market-Specific Messaging](geographic-market-messaging) | /all (geo filter)     | Focus Groups + Generate | Localized campaign copy          |

***

## Rate Limits & Production Notes

| Perigon Endpoint              | Starter              | Pro         | Strategy                    |
| ----------------------------- | -------------------- | ----------- | --------------------------- |
| `/all`                        | 100 req/day          | 10K req/day | Cache results by topic+date |
| `/stories/all`                | 100 req/day (shared) | 10K req/day | One call per topic per run  |
| `/people/all`, `/sources/all` | Shared pool          | Shared pool | Cache source lists daily    |

<Warning>
  Perigon rate limits are plan-dependent. The jobs above use 1-6 Perigon calls each — safe on Starter for daily runs, comfortable on Pro for hourly. Use header-based auth (`x-api-key`) in production to avoid API keys in URLs. Store credentials in env vars. Deduplicate articles by `articleId` when combining multiple queries. Monitor Mavera credits at [Dashboard](https://app.mavera.io/settings/usage).
</Warning>

***

<CardGroup cols={3}>
  <Card title="All Integrations" icon="plug" href="/integrations" />

  <Card title="Perigon API Docs" icon="newspaper" href="https://docs.goperigon.com/" />

  <Card title="Personas" icon="user" href="/features/personas" />

  <Card title="Focus Groups" icon="users" href="/features/focus-groups" />

  <Card title="Mave Agent" icon="brain" href="/features/mave-agent" />

  <Card title="Generate" icon="pen" href="/features/generate" />
</CardGroup>