borghei/Claude-Skills / project-management/notion-pm
notion-pm
VerifiedDesigns Notion databases, views and page structure for PRDs, OKRs, roadmaps and decisions, and writes REST API calls. Use when asked to "design a PRD database", sync Notion with Jira or Linear, or script the Notion API.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.2 KB |
| assets/notion-okr-template.md | markdown | 6.9 KB |
| assets/notion-prd-template.md | markdown | 4.5 KB |
| assets/notion-roadmap-template.md | markdown | 5.1 KB |
| examples/product-team-workspace-buildout.md | markdown | 10.5 KB |
| references/notion-api-patterns.md | markdown | 13.8 KB |
| references/notion-database-design-for-pm.md | markdown | 9.8 KB |
| references/notion-pm-playbook.md | markdown | 16.9 KB |
| references/red-flags.md | markdown | 10.3 KB |
references/notion-api-patterns.md
View on GitHub# Notion REST API Patterns
Canonical Notion API calls for PM workflows. Endpoint base: `https://api.notion.com/v1/`. Auth: `Authorization: Bearer secret_...` (internal integration token) or OAuth2. Every request must include a `Notion-Version` header. These recipes target **`2025-09-03`**, the version that introduced **data sources** (as of September 2026; a newer version, `2026-03-11`, also exists — see the version note below).
All examples use `curl` for clarity; the same JSON bodies apply to any HTTP client.
---
## 1. Authentication & Connection
```bash
export NOTION_TOKEN="secret_..."
export NOTION_VERSION="2025-09-03"
NOTION_HEADERS=(
-H "Authorization: Bearer $NOTION_TOKEN"
-H "Notion-Version: $NOTION_VERSION"
-H "Content-Type: application/json"
)
```
An integration only sees pages and databases that have been **explicitly shared** with it (open the database → "..." → Add connections). 404s are almost always a missing share.
### Version note — databases vs. data sources (as of September 2026)
From `Notion-Version: 2025-09-03`, a **database** is a container that holds one or more **data sources**; the rows, the property schema and queries live on the data source. What changed versus `2022-06-28`:
| Task | `2022-06-28` | `2025-09-03` |
|---|---|---|
| Query rows | `POST /v1/databases/{database_id}/query` | `POST /v1/data_sources/{data_source_id}/query` |
| Read property schema | `GET /v1/databases/{database_id}` | `GET /v1/data_sources/{data_source_id}` |
| Change property schema | `PATCH /v1/databases/{database_id}` | `PATCH /v1/data_sources/{data_source_id}` |
| Create a row (page) | `"parent": { "database_id": ... }` | `"parent": { "type": "data_source_id", "data_source_id": ... }` |
| Search filter for DBs | `"value": "database"` | `"value": "data_source"` |
| Create a database | `properties` at top level | `properties` nested under `initial_data_source` |
| Webhook events | `database.content_updated`, `database.schema_updated` | `data_source.content_updated`, `data_source.schema_updated` |
`PATCH /v1/databases/{database_id}` still exists but now only covers database-level fields (`parent`, `title`, `is_inline`, `icon`, `cover`, `in_trash`). Relation properties must reference a `data_source_id`; `database_id` is no longer accepted in requests. Always send the version header explicitly — do not mix versions within one integration.
`2026-03-11` is the latest version as of September 2026. Its breaking changes: `archived` replaced by `in_trash`, the append-children `after` parameter replaced by a `position` object, and the `transcription` block type renamed to `meeting_notes`. The recipes below do not use any of those fields. Notion states it has no current plans to stop supporting older versions.
Sources: https://developers.notion.com/docs/upgrade-guide-2025-09-03 · https://developers.notion.com/docs/upgrade-guide-2026-03-11 · https://developers.notion.com/reference/versioning
---
## 2. Discovery — IDs You Need First
Notion IDs are 32-char hex (sometimes hyphenated). The API accepts both forms.
**Resolve a database to its data source ID** (required before querying or creating rows):
```bash
curl -X GET "https://api.notion.com/v1/databases/<db_id>" "${NOTION_HEADERS[@]}"
```
The response lists the database's data sources:
```json
"data_sources": [
{ "id": "<data_source_id>", "name": "PRDs" }
]
```
Most PM databases have exactly one data source; cache its `id`. If a database has several, pick by `name` — never assume index 0.
**Retrieve the property schema** (lives on the data source):
```bash
curl -X GET "https://api.notion.com/v1/data_sources/<data_source_id>" "${NOTION_HEADERS[@]}"
```
Use the `properties` in the response to inspect property names, types, and the exact option strings for `select` / `status` / `multi_select` properties. Selectable options are **case-sensitive** when set via the API.
**Search for a database by title** (returns data source objects on `2025-09-03`):
```bash
curl -X POST "https://api.notion.com/v1/search" "${NOTION_HEADERS[@]}" \
-d '{
"query": "PRDs",
"filter": { "value": "data_source", "property": "object" }
}'
```
**Get a user (for the People property)**:
```bash
curl -X GET "https://api.notion.com/v1/users" "${NOTION_HEADERS[@]}"
```
Cache user IDs; they are stable.
---
## 3. Querying Databases (via their data source)
**Basic query**:
```bash
curl -X POST "https://api.notion.com/v1/data_sources/<data_source_id>/query" "${NOTION_HEADERS[@]}" \
-d '{
"filter": { "property": "Status", "status": { "equals": "In Review" } },
"sorts": [{ "property": "Target Date", "direction": "ascending" }],
"page_size": 100
}'
```
**Compound filter (AND)**:
```json
{
"filter": {
"and": [
{ "property": "Owner", "people": { "contains": "<user_id>" } },
{ "property": "Status", "status": { "does_not_equal": "Killed" } },
{ "property": "Target Date", "date": { "next_quarter": {} } }
]
}
}
```
**Compound filter (OR)**:
```json
{
"filter": {
"or": [
{ "property": "Status", "status": { "equals": "At Risk" } },
{ "property": "Status", "status": { "equals": "Off Track" } }
]
}
}
```
**Filter by relation**:
```json
{ "filter": { "property": "OKR", "relation": { "contains": "<okr_page_id>" } } }
```
**Pagination**:
```json
{ "page_size": 100, "start_cursor": "<cursor_from_previous_response>" }
```
Loop while `has_more` is true, passing `next_cursor` as the next `start_cursor`.
---
## 4. Creating a Page in a Database
**Minimal PRD page**:
```bash
curl -X POST "https://api.notion.com/v1/pages" "${NOTION_HEADERS[@]}" \
-d '{
"parent": { "type": "data_source_id", "data_source_id": "<prd_data_source_id>" },
"properties": {
"Title": { "title": [{ "text": { "content": "PRD: Self-Serve Signup" } }] },
"Status": { "status": { "name": "Draft" } },
"Owner": { "people": [{ "id": "<user_id>" }] },
"Target Date": { "date": { "start": "2026-09-30" } },
"Priority": { "select": { "name": "P1" } }
},
"children": [
{ "object": "block", "type": "heading_2",
"heading_2": { "rich_text": [{ "text": { "content": "Problem" } }] } },
{ "object": "block", "type": "paragraph",
"paragraph": { "rich_text": [{ "text": { "content": "Today, new users must..." } }] } },
{ "object": "block", "type": "callout",
"callout": {
"icon": { "type": "emoji", "emoji": "ℹ" },
"rich_text": [{ "text": { "content": "Reviewed by Eng + Design on 2026-05-19." } }]
}
}
]
}'
```
**Setting a relation**:
```json
{
"properties": {
"OKR": { "relation": [{ "id": "<okr_page_id_1>" }, { "id": "<okr_page_id_2>" }] }
}
}
```
**Setting multi_select**:
```json
{ "properties": { "Areas": { "multi_select": [{ "name": "API" }, { "name": "Web" }] } } }
```
---
## 5. Updating a Page
**Update properties only** (does not touch the page body):
```bash
curl -X PATCH "https://api.notion.com/v1/pages/<page_id>" "${NOTION_HEADERS[@]}" \
-d '{
"properties": {
"Status": { "status": { "name": "Approved" } },
"Approved On": { "date": { "start": "2026-05-21" } }
}
}'
```
**Move a page to trash** (Notion's "delete"):
```bash
curl -X PATCH "https://api.notion.com/v1/pages/<page_id>" "${NOTION_HEADERS[@]}" \
-d '{ "in_trash": true }'
```
**Restore from trash**:
```json
{ "in_trash": false }
```
Use `in_trash` rather than the older `archived` field — `2026-03-11` removes `archived`.
---
## 6. Working with Blocks (Page Body)
**Append children to a page**:
```bash
curl -X PATCH "https://api.notion.com/v1/blocks/<page_id>/children" "${NOTION_HEADERS[@]}" \
-d '{
"children": [
{ "object": "block", "type": "heading_3",
"heading_3": { "rich_text": [{ "text": { "content": "Open questions" } }] } },
{ "object": "block", "type": "toggle",
"toggle": {
"rich_text": [{ "text": { "content": "Should we A/B test the new flow?" } }],
"children": [
{ "object": "block", "type": "paragraph",
"paragraph": { "rich_text": [{ "text": { "content": "Pro: data. Con: 2 weeks." } }] } }
]
}
}
]
}'
```
**Common block types for PM artifacts**:
| Block | JSON `type` value | Use |
|---|---|---|
| Heading | `heading_1`, `heading_2`, `heading_3` | Sections |
| Paragraph | `paragraph` | Body text |
| Bulleted list | `bulleted_list_item` | Lists |
| Numbered list | `numbered_list_item` | Ordered lists |
| To-do | `to_do` (`checked: true/false`) | Action items |
| Callout | `callout` (with `icon`) | Notes, warnings, decisions |
| Toggle | `toggle` (with `children`) | Collapsible details |
| Code | `code` (`language: "javascript"`) | Code snippets |
| Quote | `quote` | Customer voice, pull-quotes |
| Divider | `divider` | Section separator |
| Bookmark | `bookmark` (`url: "..."`) | Rich link preview |
| Embed | `embed` (`url: "..."`) | Figma, Loom, etc. |
| Table | `table` + child `table_row` blocks | Tables |
| Synced block | `synced_block` | Reusable content |
**Read a block** (for fetching the page body):
```bash
curl -X GET "https://api.notion.com/v1/blocks/<block_id>" "${NOTION_HEADERS[@]}"
```
**List a page's children**:
```bash
curl -X GET "https://api.notion.com/v1/blocks/<page_id>/children?page_size=100" "${NOTION_HEADERS[@]}"
```
**Update a block**:
```bash
curl -X PATCH "https://api.notion.com/v1/blocks/<block_id>" "${NOTION_HEADERS[@]}" \
-d '{ "to_do": { "checked": true } }'
```
**Delete (archive) a block**:
```bash
curl -X DELETE "https://api.notion.com/v1/blocks/<block_id>" "${NOTION_HEADERS[@]}"
```
---
## 7. Creating a Database
Databases can be created as children of an existing page. Use this sparingly; most workspaces should design DBs in the UI and then drive them programmatically.
```bash
curl -X POST "https://api.notion.com/v1/databases" "${NOTION_HEADERS[@]}" \
-d '{
"parent": { "type": "page_id", "page_id": "<parent_page_id>" },
"title": [{ "type": "text", "text": { "content": "Decisions" } }],
"initial_data_source": {
"properties": {
"Title": { "title": {} },
"Status": { "select": { "options": [
{ "name": "Proposed", "color": "yellow" },
{ "name": "Approved", "color": "green" },
{ "name": "Superseded", "color": "gray" }
]}},
"Date": { "date": {} },
"Owner": { "people": {} },
"ID": { "unique_id": { "prefix": "DEC" } }
}
}
}'
```
On `2025-09-03` the schema goes under `initial_data_source.properties`. The response includes the new database's `data_sources[]` — store that `id` for later queries and page creation.
---
## 8. Rich Text Structure
Every text-bearing block uses a `rich_text` array. The minimal form:
```json
{ "text": { "content": "Hello" } }
```
With link:
```json
{ "text": { "content": "Linear", "link": { "url": "https://linear.app/..." } } }
```
With formatting:
```json
{
"text": { "content": "important" },
"annotations": {
"bold": true, "italic": false, "code": false, "strikethrough": false, "underline": false,
"color": "red"
}
}
```
Mentions (a person):
```json
{ "mention": { "type": "user", "user": { "id": "<user_id>" } } }
```
Mentions (a page):
```json
{ "mention": { "type": "page", "page": { "id": "<page_id>" } } }
```
Mentions (a date):
```json
{ "mention": { "type": "date", "date": { "start": "2026-05-21" } } }
```
---
## 9. Sync Pattern Recipes
### Notion → Linear (create Project on PRD approval)
1. Webhook source: PRD status changes to Approved (handled by Zapier/Make/custom poller).
2. Read PRD properties via Notion API.
3. Look up Linear team ID and label IDs from cache.
4. Call Linear's `projectCreate` mutation (see `linear-expert/references/linear-graphql-patterns.md`).
5. Store the returned Linear Project URL in the PRD's `Linear Project` property via Notion PATCH.
### Linear → Notion (roll up project progress)
1. Scheduled job (nightly).
2. For each PRD with a non-null `Linear Project` URL: extract project ID; query Linear for project progress.
3. PATCH the PRD's `Linear Progress` number property and `Linear State` select property.
### GitHub → Notion (log ADR as a Decision)
1. GitHub Action on push to `main` matching `docs/adr/*.md`.
2. Parse the ADR front matter (title, status, date, drivers).
3. POST to Notion's pages endpoint with `parent: { "type": "data_source_id", "data_source_id": "<decisions_data_source_id>" }`.
---
## 10. Rate Limits and Resilience
- ~3 requests/second per integration, with short bursts permitted.
- On `429`, response includes `Retry-After` header (seconds). Honor it.
- For bulk writes, batch and sleep 300-500ms between calls.
- Wrap mutating calls in idempotency checks where possible (search by title before create).
- Cache data source IDs and schemas; refresh only when a 400 indicates a property mismatch.
## 11. Quick Reference
| Operation | Method | Endpoint |
|---|---|---|
| Get DB (→ `data_sources[].id`) | GET | `/v1/databases/{database_id}` |
| Query rows | POST | `/v1/data_sources/{data_source_id}/query` |
| Get property schema | GET | `/v1/data_sources/{data_source_id}` |
| Update property schema | PATCH | `/v1/data_sources/{data_source_id}` |
| Create DB | POST | `/v1/databases` (schema in `initial_data_source`) |
| Update DB title/icon/parent | PATCH | `/v1/databases/{database_id}` |
| Get page | GET | `/v1/pages/{id}` |
| Create page | POST | `/v1/pages` |
| Update page props | PATCH | `/v1/pages/{id}` |
| Get block | GET | `/v1/blocks/{id}` |
| List children | GET | `/v1/blocks/{id}/children` |
| Append children | PATCH | `/v1/blocks/{id}/children` |
| Update block | PATCH | `/v1/blocks/{id}` |
| Delete (archive) block | DELETE | `/v1/blocks/{id}` |
| List users | GET | `/v1/users` |
| Search | POST | `/v1/search` |
Endpoints above are for `Notion-Version: 2025-09-03` (as of September 2026). Full reference: https://developers.notion.com/reference/intro
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |