Notion - Mavera

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_...`

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.

Prerequisites

Create a Notion integration

Go to notion.so/my-integrations → New integration → select workspace → copy the Internal Integration Token.

Share pages/databases with the integration

Open each Notion database or page → click ⋯ → Connections → find your integration → Confirm. Without this, API calls return 404.

Mavera API key

Get your key from Mavera dashboard.

Environment variables

export NOTION_API_KEY="ntn_xxxxxxxxxxxxx"
export MAVERA_API_KEY="mvra_live_xxxxx"

Jobs

#	Job	Notion Data	Mavera Surface	Output
1	Content Calendar → Generate Pipeline	Database query (content calendar)	Generate	Draft content per planned piece
2	Meeting Notes → Mave Analysis	Pages (meeting notes)	Mave Agent	Action items, decisions, themes
3	Product Requirements → Focus Group	Pages (PRDs)	Personas + Focus Groups	User persona interest ratings
4	Knowledge Base → Brand Voice	Pages (wiki/docs)	Brand Voice	Voice profile from internal docs
5	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

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.

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. Generation and Focus Group calls consume the most credits.

​API Reference Card

​Prerequisites

​Jobs

​Rate Limits & Production Notes

All Integrations

Notion API Docs

Brand Voice

Focus Groups

Mave Agent

Generate

API Reference Card

Prerequisites

Jobs

Rate Limits & Production Notes