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

# Notion

> 5 production-ready jobs — content calendar generation pipelines, meeting notes analysis, PRD focus groups, knowledge base brand voice extraction, and competitive wiki battle cards

Notion databases and pages hold your team's planning, decisions, research, and competitive intelligence. These five jobs pull data from Notion's API into Mavera's surfaces (Generate, Mave Agent, Focus Groups, Brand Voice) to turn passive documentation into active marketing assets.

***

## API Reference Card

| Detail             | Value                                                                        |
| ------------------ | ---------------------------------------------------------------------------- |
| **Base URL**       | `https://api.notion.com/v1`                                                  |
| **Auth**           | Internal integrations: Bearer token. Public integrations: OAuth 2.0          |
| **Version header** | `Notion-Version: 2022-06-28` (required on every request)                     |
| **Rate limits**    | 3 requests/second average; bursts above that return `429`                    |
| **Key endpoints**  | `POST /databases/{id}/query`, `GET /pages/{id}`, `GET /blocks/{id}/children` |
| **Mavera base**    | `https://app.mavera.io/api/v1`                                               |
| **Mavera auth**    | `Authorization: Bearer mvra_live_...`                                        |

<Info>
  All examples use `NOTION_API_KEY` (an internal integration token starting with `ntn_` or `secret_`) and `MAVERA_API_KEY`. The integration must be explicitly shared with each database or page it accesses — open the page in Notion → ⋯ → Connections → add your integration.
</Info>

***

## Prerequisites

<Steps>
  <Step title="Create a Notion integration">Go to [notion.so/my-integrations](https://www.notion.so/my-integrations) → New integration → select workspace → copy the Internal Integration Token.</Step>
  <Step title="Share pages/databases with the integration">Open each Notion database or page → click ⋯ → Connections → find your integration → Confirm. Without this, API calls return 404.</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 NOTION_API_KEY="ntn_xxxxxxxxxxxxx"
    export MAVERA_API_KEY="mvra_live_xxxxx"
    ```
  </Step>
</Steps>

***

## Jobs

| # | Job                                                               | Notion Data                       | Mavera Surface          | Output                           |
| - | ----------------------------------------------------------------- | --------------------------------- | ----------------------- | -------------------------------- |
| 1 | [Content Calendar → Generate Pipeline](content-calendar-pipeline) | Database query (content calendar) | Generate                | Draft content per planned piece  |
| 2 | [Meeting Notes → Mave Analysis](meeting-notes-analysis)           | Pages (meeting notes)             | Mave Agent              | Action items, decisions, themes  |
| 3 | [Product Requirements → Focus Group](prd-focus-group)             | Pages (PRDs)                      | Personas + Focus Groups | User persona interest ratings    |
| 4 | [Knowledge Base → Brand Voice](knowledge-base-brand-voice)        | Pages (wiki/docs)                 | Brand Voice             | Voice profile from internal docs |
| 5 | [Competitive Wiki → Battle Cards](competitive-wiki-battle-cards)  | Pages (competitive intel)         | Mave Agent + Generate   | AI-enriched battle cards         |

***

## Rate Limits & Production Notes

| Notion Endpoint               | Limit     | Strategy                                    |
| ----------------------------- | --------- | ------------------------------------------- |
| All endpoints (average)       | 3 req/sec | 400ms minimum delay between calls           |
| `POST /databases/{id}/query`  | 3 req/sec | Paginate with `start_cursor`; cache results |
| `GET /blocks/{id}/children`   | 3 req/sec | Paginate; 100 blocks per page max           |
| `PATCH /pages/{id}`           | 3 req/sec | Batch updates with delays                   |
| `PATCH /blocks/{id}/children` | 3 req/sec | Max 100 blocks per append call              |

<Warning>
  Notion's rate limit is a **3 requests/second average** — not a hard burst limit. Brief bursts above 3 are tolerated, but sustained bursts trigger `429` responses with a `Retry-After` header. All code includes 400ms+ delays between calls. For production, implement a token-bucket rate limiter.
</Warning>

**Production checklist:**

* **Authentication**: Internal integration tokens don't expire but are workspace-scoped. For multi-workspace apps, use OAuth 2.0 public integrations.
* **Version header**: Always include `Notion-Version: 2022-06-28`. Omitting it may return unexpected response shapes.
* **Pagination**: All list endpoints return max 100 items. Use `next_cursor` / `has_more` to paginate.
* **Block limits**: Append calls accept max 100 blocks. Rich text content is limited to 2000 characters per text object.
* **Caching**: Cache Notion database schemas and page metadata. Re-fetch page content only when `last_edited_time` changes.
* **Mavera credits**: Monitor usage at [Dashboard](https://app.mavera.io/settings/usage). Generation and Focus Group calls consume the most credits.

***

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

  <Card title="Notion API Docs" icon="book" href="https://developers.notion.com/reference/intro" />

  <Card title="Brand Voice" icon="microphone" href="/features/brand-voice" />

  <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/content-generation" />
</CardGroup>