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.
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 |
- 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_moreto 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_timechanges. - Mavera credits: Monitor usage at Dashboard. Generation and Focus Group calls consume the most credits.