universal-baseline-2026-03-13

{
  "url": "https://developers.notion.com/llms-full.txt",
  "prompt": "Extract ALL content from this machine-readable documentation. I need comprehensive details on:\n1. All API endpoints and their purposes\n2. All object types (pages, databases, blocks, properties, users, comments, search)\n3. All property types supported in databases\n4. All block types supported\n5. Rate limits and authentication details\n6. CRUD operations available for each object type\n7. Filtering and sorting capabilities\n8. Any limitations, gotchas, or gaps mentioned\n9. Pagination details\n10. Any mentions of MCP, CLI, SDK, or agent interfaces\nReturn as much detail as possible - do not summarize, be exhaustive."
}

REDIRECT DETECTED: The URL redirects to a different host.

Original URL: https://www.notion.so/help/guides
Redirect URL: https://www.notion.com/help/guides
Status: 301 Moved Permanently

To complete your request, I need to fetch content from the redirected URL. Please use WebFetch again with these parameters:
- url: "https://www.notion.com/help/guides"
- prompt: "Extract all content about Notion's product capabilities. I need:
1. What features does Notion offer (databases, pages, wikis, projects, etc.)
2. What content types and block types are available in the UI
3. Database features (views, filters, relations, rollups, formulas)
4. Collaboration features
5. Any features that might not be available via API
6. AI features
7. Automation features
Be thorough."

# Notion API Reference - Comprehensive Extraction

## Base Information
- **Base URL**: `https://api.notion.com`
- **Protocol**: HTTPS required
- **Format**: RESTful API with JSON request/response bodies
- **Supported Methods**: GET, POST, PATCH, DELETE

## Authentication
- Integration token required (obtained from integration settings page)
- Token must be included in Authorization header
- Header format: `Authorization: Bearer <token>`
- Admin workspace access needed to retrieve tokens

## API Versioning
- Current version specified via header: `Notion-Version: 2026-03-11`

## JSON Conventions
- Top-level resources contain `"object"` property indicating type (database, user, etc.)
- Resources identified by UUIDv4 `"id"` (dashes optional in requests)
- Property naming uses `snake_case`
- "Temporal values are encoded in ISO 8601 strings" with datetimes including time (`2020-08-12T02:12:33.231Z`) and dates as date-only (`2020-08-12`)
- Empty strings unsupported; use explicit `null` instead

## Paginated Endpoints

| Method | Endpoint |
|--------|----------|
| GET | List all users |
| GET | List block children |
| GET | List comments |
| GET | Retrieve page property item |
| GET | List file uploads |
| GET | List data source templates |
| POST | Query data source |
| POST | Search |

## Pagination Parameters
- `page_size`: Default 100, maximum 100 items
- `start_cursor`: Opaque token from previous `next_cursor` response

## Pagination Response Fields
- `has_more`: Boolean indicating additional results exist
- `next_cursor`: String for retrieving next page (when `has_more` is true)
- `object`: Always `"list"`
- `results`: Array of endpoint-specific objects
- `type`: Indicates result object type (block, comment, user, etc.)

## Rate Limiting & Error Handling
**Not documented in provided content**

## Object Schemas
**Not detailed in provided content** (reference directs to individual endpoint documentation)

## Additional Resources
- JavaScript SDK available at GitHub
- cURL examples provided for endpoints
- Complete documentation index: `https://developers.notion.com/llms.txt`

# Comprehensive Notion API Documentation Extract

## Authentication & Rate Limits

The documentation mentions Enterprise-grade compliance features requiring Notion Enterprise plans, but **specific rate limit numbers are not provided** in the extracted content. Authentication uses Bearer tokens (format: `Bearer ntn_****` or `Bearer $NOTION_API_KEY`).

## API Endpoints Overview

### File Management Endpoints
- **POST /v1/file_uploads** — Create file upload objects (single or multi-part mode)
- **GET /v1/file_uploads/:file_upload_id** — Retrieve file upload status
- **POST /v1/file_uploads/:file_upload_id/send** — Send file parts or complete upload
- **POST /v1/file_uploads/:file_upload_id/complete** — Finalize multi-part uploads

### Page & Content Endpoints
- **POST /v1/pages** — Create pages (supports markdown, templates, properties)
- **GET /v1/pages/:page_id** — Retrieve page with properties and metadata
- **PATCH /v1/pages/:page_id** — Update page (supports template application, content erasure)
- **GET /v1/pages/:page_id/markdown** — Retrieve page as Notion-flavored Markdown
- **PATCH /v1/pages/:page_id/markdown** — Update page via Markdown format
- **GET /v1/blocks/:block_id/children** — Retrieve block children/page content

### Database Template Endpoints
- **GET /v1/data_sources/:data_source_id/templates** — List available templates with filtering by name, pagination support (page_size 1-100, start_cursor for pagination)

### Data Structure Endpoints
- **POST /v1/data_sources/:data_source_id** — Create databases/data sources
- **PATCH /v1/data_sources** — Modify database schema

### Workspace & Member Endpoints
- **Workspace users endpoint** — Referenced as "workspace.users_read" event but exact endpoint path not provided
- **Workspace teams endpoint** — Referenced as "workspace.teams_read" event but exact endpoint path not provided

## Object Types & Properties

### Page Object
Contains: `id`, `created_time`, `last_edited_time`, `properties` (varies by database schema), `parent` (can reference data_source_id), `cover`, `icon`, `archived` status, `public_url` for shared pages.

**Template Parameters**: `template[type]` accepts `"none"`, `"default"`, or `"template_id"`; `template[timezone]` supports IANA timezone strings (e.g., `America/New_York`, `Europe/London`, `Asia/Tokyo`); optional `erase_content` flag for destructive replacement.

### File Upload Object
Properties: `id`, `upload_url`, `status` (pending/uploaded/failed), `filename`, `content_type`, `file_import_result` (on failure: contains error codes like `file_upload_invalid_size`).

**Modes**: 
- `"single_part"` — Files up to 20 MB
- `"multi_part"` — Files up to 5 GB (requires `number_of_parts`, each part 5-20 MB except final < 5 MB)
- `"external_url"` — Import from public URLs (validates SSL, Content-Type header, Content-Length against workspace limits)

### File Object (Retrieved)
- `type` — `"file"`, `"external"`, or `"file_upload"`
- `url` — Temporary signed link (expires 1 hour)
- `expiry_time` — ISO 8601 timestamp
- `name` — For files in database properties

### Block Types (Partial List from Markdown Support)
Text, Headings (H1-H6, H5-H6 convert to H4), Lists (bulleted/numbered), To-do items (checked/unchecked), Quotes, Toggles, Callouts, Code blocks (with language specification), Equations, Tables, Dividers, Empty blocks, Columns, Images/Audio/Video/PDF/Files (with captions), Page references, Database references, Table of contents, Synced blocks.

**Block Attributes**: `color` (text: gray, brown, orange, yellow, green, blue, purple, pink, red; background: append `_bg` to text colors), toggles (`toggle="true"`), callouts (icon emoji support).

### Audit Log Event Objects
Events include: `entity` (type and id), `timestamp`, `actor` (user performing action), `action` (specific event type).

**Event Types by Category**:
- **Page events** (37 types) — creation, editing, deletion, permission changes, file operations, comments, suggestions, automation
- **Data source events** (9 types) — database creation, schema edits, permission rules, trash operations
- **Workspace events** (90+ types) — member management, integrations, SAML/SCIM, encryption key rotation, settings changes, content export
- **Account events** (14 types) — login, logout, MFA changes, password management, email/name updates, support access
- **Teamspace events** (25 types) — creation, membership, permissions, settings
- **Form events** (5 types) — creation, editing, responses, viewing
- **Organization events** (55+ types) — legal holds, IP allowlists, domain management, workspace consolidation

### SIEM Event Types (Webhook Format)
Mirrors audit log events with dot-notation naming:
- **page.*** — `page.created`, `page.content_edited`, `page.deleted`, `page.permanently_deleted`, `page.exported`, `page.viewed`, `page.permissions.*`, etc.
- **database.*** — `database.schema_edited`, `database.permissions.can_create_pages.*`
- **workspace.*** — `workspace.content_exported`, `workspace.members_exported`, `workspace.custom_agent.created`, etc.
- **user.*** — `user.login`, `user.logout`, `user.deleted`, `user.suspended`, `user.unsuspended`, `user.settings.*`
- **teamspace.*** — `teamspace.created`, `teamspace.archived`, `teamspace.permissions.*`, `teamspace.settings.*`
- **form.*** — `form.created`, `form.viewed`, `form_response.created`

**Page Audience Values** (for SIEM events): Private, Internal, External, Public.

## Rich Text & Markdown Format

### Notion-Flavored Markdown Features
- **Formatting**: Bold (`**text**`), Italic (`*text*`), Strikethrough (`~~text~~`), Underline (`<span underline="true">text</span>`), Inline code (`` `code` ``), Inline math (`$equation$`)
- **Links**: `[text](URL)`
- **Mentions**: 
  - `<mention-user url="URL">User name</mention-user>`
  - `<mention-page url="URL">Page title</mention-page>`
  - `<mention-database url="URL">Database name</mention-database>`
  - `<mention-date start="YYYY-MM-DD" end="YYYY-MM-DD"/>`
  - `<mention-date start="YYYY-MM-DD" startTime="HH:mm" timeZone="IANA_TIMEZONE"/>`
- **Custom emoji**: `:emoji_name:`
- **Citations**: `[^URL]`
- **Line breaks**: `<br>`
- **Escaping**: Backslash escapes for `\ * ~ `` $ [ ] < > { } | ^` (not inside code blocks)
- **Indentation**: Tabs for nesting (child blocks indented one tab deeper)

### Table Markdown Support
```html
<table fit-page-width="true|false" header-row="true|false" header-column="true|false">
  <colgroup><col color="Color"/></colgroup>
  <tr color="Color"><td color="Color">Content</td></tr>
</table>
```

### Complex Block Types in Markdown
- **Callouts**: `<callout icon="emoji" color="Color">Content</callout>` (supports multiple nested blocks)
- **Toggles**: HTML `<details>` or heading with `{toggle="true"}`
- **Columns**: `<columns><column>Children</column></columns>`
- **Synced blocks**: `<synced_block url="URL">` and `<synced_block_reference url="URL">`
- **Database references**: `<database url="URL" inline="true|false" icon="Emoji"/>`

## Template System

### List Data Source Templates
Query parameters: `name` (substring filter, case-insensitive), `page_size` (1-100), `start_cursor` (nullable).

Response includes: `id` (UUID v4), `name`, `is_default` boolean, `has_more`, `next_cursor`.

### Template Application Rules
- **Default template**: Use when data source has one marked as default; timezone optional
- **Specific template**: Pass `template[template_id]` (UUID with/without dashes); timezone optional
- **Processing**: Asynchronously populates page; returns blank page immediately
- **Placeholder resolution**: Variables like `@now`, `@today` resolve per specified timezone
- **Events**: Emits `page.created` (deferred until ready) or `page.created` + subsequent `page.content_updated` in rare cases
- **Webhook confirmation**: Listen for `page.content_updated` or call `GET /v1/blocks/:page_id/children` to verify content population
- **Existing pages**: `PATCH /v1/pages/:page_id` also supports template application; `erase_content=true` replaces existing content (destructive)

## File Size & Storage Limits

- **Free workspace**: 5 MB per-file limit
- **Paid workspace**: 5 GB per-file limit
- **Multi-part uploads**: 5 GB total maximum
- **Part size convention**: Each part 5-20 MB (except final < 5 MB); recommended 10 MB parts
- **Retrieval**: File URLs valid 1 hour (must re-fetch to refresh)

## Integrations & Connections

### Custom Agent Features
- **Cursor integration** — Connect custom agents to Cursor IDE for PR creation and bug fixing from Notion tasks
- **Setup**: Add Cursor connection in agent Settings → Tools & access → Add connection
- **Cursor requirements**: User API Key from Cursor dashboard (integrations tab)
- **Permissions**: Share engineering task databases and spec pages with agent
- **Workflow**: Assign database pages or @mention agent in comments; agent can run asynchronously

### Integration Types
- **Internal integrations** — Created in workspace; settings include name, icon, capabilities (read content, insert comments, etc.)
- **Public/External integrations** — Connected via workspace settings; can be disconnected for all users
- **Integration webhooks** — Can fail due to repeated delivery failures; reactivated after successful recovery

### MCP (Model Context Protocol) Support
- **Allowlist**: Can be enabled/disabled; clients can be added/removed from allowlist
- **Server connections**: MCP servers can connect to workspaces
- **Template support**: Notion MCP supports `notion-create-pages` and `notion-update-page` tools with `template_id` parameter; fetch templates via `notion-fetch` tool

## Webhooks & Events

### Webhook Delivery
- **Event aggregation**: Quick successive events may combine into single webhook (e.g., `page.created` deferred until `page.content_updated` completes)
- **Types**: `page.created`, `page.content_updated`, `file_upload.complete`, `file_upload.upload_failed`
- **Payload**: Contains `entity` (type, id), `data`, timestamp

### Failure Handling
- **File imports**: `file_upload.upload_failed` returns `data[file_import_result][error]` with error codes (e.g., `file_upload_invalid_size`)
- **Webhook inactivation**: `workspace.integration_webhook_inactivated` after repeated delivery failures
- **Webhook reactivation**: `workspace.integration_webhook_reactivated` after recovery

## Compliance & Security Features

### Audit Logging
Available on Enterprise plans; exported via `workspace.audit_log_exported` or `organization.audit_log_exported` events.

### SIEM Integration
Webhook-based real-time security monitoring; events correspond 1:1 with audit log entries.

### Data Retention
Custom settings: `workspace.settings.delete_from_trash_delay` and `workspace.settings.purge_delay` control automatic deletion timeframes.

### Encryption Management
- **WEK** (Workspace Encryption Key) — `workspace.ekm.wek.generated`, `workspace.ekm.wek.revoked`
- **DEK** (Data Encryption Key) — `workspace.ekm.dek.rotation.started`, `workspace.ekm.dek.rotation.completed`
- **CMK** (Customer-Managed Key) — `workspace.ekm.cmk.rotation.completed`

### SAML/SCIM
- **SAML**: `workspace.saml_sso_idp_metadata_url_*`, `workspace.saml_sso_idp_metadata_xml_*`, `workspace.saml_authorization`
- **SCIM**: `workspace.scim_token_generated`, `workspace.scim_token_revoked`
- **Managed users**: Password clearing, logout, session duration management, profile edit restrictions

### Legal Hold (Organization-level)
Events: `organization.legal_hold_created`, `organization.legal_hold_export_content_created`, `organization.legal_hold_member_added/removed`, `organization.legal_hold_released`

## CLI & SDK References

### Notion SDK (TypeScript/JavaScript)
- **Minimum version**: v5.3.0 required for template and file upload APIs
- **Minimum API version**: `2025-09-03` required with SDK v5+
- **Custom requests**: `notion.request(...)` syntax available for pre-v5.3.0 versions

### Claude Code CLI
Documentation mentions "Claude Code, Anthropic's official CLI for Claude" but provides no Notion-specific integration details in this extract.

## Known Limitations & Gotchas

1. **Template ID format** — Accepts UUID with or without dashes; can use any page as template (but schema must match destination database)
2. **Template variables** — `@now`, `@today` require timezone specification; defaults to user timezone (public integrations) or UTC (internal integrations)
3. **File expiry** — Temporary URLs expire after 1 hour; must re-fetch to refresh
4. **External file imports** — Require SSL-enabled, publicly accessible URLs with `Content-Type` header; size validated via `Content-Length` (or re-validated at completion)
5. **Multi-part uploads** — Parts can be sent in parallel but all must complete before calling Complete endpoint; size re-validated at completion
6. **Template application timing** — Page returned immediately but content populated asynchronously; webhook or polling required for confirmation
7. **Synced blocks** — Supported in Markdown but require proper URL references
8. **Block children limits** — Documentation references `Retrieve block children` but does not specify pagination or maximum count per request
9. **Data source operations** — Some emit as `page.*` events "for historical reasons" (SIEM documentation)
10. **Markdown escaping** — No escaping needed inside code blocks; characters outside code blocks require backslash escaping

## Missing/Unclear Details

- **Exact rate limit numbers** — Not provided in documentation
- **Pagination defaults** — Block children endpoint pagination not fully specified
- **Maximum page/database sizes** — Not mentioned
- **Comment/Discussion API endpoints** — Events exist (`page.discussion.comment.*`) but no CRUD endpoints documented
- **Search endpoint specifics** — Mentioned in events but no API endpoint details provided
- **User/Member object schema** — Referenced but not fully documented
- **Database property type exhaustive list** — Partial coverage only
- **Webhook retry logic** — Not specified
- **API version upgrade path details** — Only mentions v2025-09-03 as minimum for certain features
- **Organization-level API endpoints** — Events mentioned but endpoints not detailed

# Notion MCP Server: Comprehensive Overview

## Purpose & Function
This project implements an MCP (Model Context Protocol) server that integrates with the Notion API, enabling AI agents to interact with Notion workspaces programmatically. It allows Claude and other AI clients to read, create, and modify Notion content.

## Tool Capabilities (Version 2.0.0)

**Total Tools: 22**

### Core Operations:
- **Data Source/Database Tools**: Query, retrieve metadata, update, and create data sources using `query-data-source`, `retrieve-a-data-source`, `update-a-data-source`, `create-a-data-source`
- **Page Operations**: Create, retrieve, update pages; move pages to different parents
- **Search & Filtering**: Search across pages and data sources with filters and sorts
- **Comments**: Post and retrieve comments on pages
- **Template Management**: `list-data-source-templates` for available data source templates
- **Database Metadata**: `retrieve-a-database` returns database metadata including data source IDs

### Version 2.0.0 Breaking Changes:
The server migrated to Notion API 2025-09-03, replacing database-centric abstractions with data sources:
- Removed: `post-database-query`, `update-a-database`, `create-a-database`
- Added: Data source equivalents plus `move-page` and `list-data-source-templates`
- Parameter shift: `database_id` → `data_source_id`

## Authentication Methods

**Primary (Recommended):**
- Set `NOTION_TOKEN` environment variable with an internal integration secret (format: `ntn_****`)

**Advanced:**
- Use `OPENAPI_MCP_HEADERS` environment variable with custom Authorization and Notion-Version headers

**Setup Requirements:**
1. Create internal integration at `notion.so/profile/integrations`
2. Configure capabilities (optionally restrict to read-only access)
3. Grant page/database access via integration's Access tab or individual page connections

## Agent Capabilities

Agents can perform these operations:

- **Information Retrieval**: Fetch page content, database records, and metadata
- **Content Creation**: Add new pages to specified parents; create data sources
- **Content Modification**: Edit page content in Markdown; update database properties
- **Organization**: Move pages between parent locations
- **Collaboration**: Comment on pages with timestamps
- **Querying**: Search workspaces with filters and sorting

Example tasks: "Comment 'Hello MCP' on page 'Getting started'" or "Add page titled 'Notion MCP' to page 'Development'"

## Installation & Configuration

**Via npm (Recommended):**
```
Cursor/Claude Desktop: Add to `.cursor/mcp.json` or `claude_desktop_config.json`
```
Configuration includes server command with `npx @notionhq/notion-mcp-server` and `NOTION_TOKEN` environment variable.

**Via Docker:**
- Official Docker Hub image: `mcp/notion`
- Local build option available via `docker compose build`

**Transport Modes:**
- STDIO (default): Standard input/output communication
- Streamable HTTP: Web-based access on configurable port (default 3000) with bearer token authentication

**HTTP Authentication Options:**
- Auto-generated development token
- Custom CLI argument `--auth-token`
- Environment variable `AUTH_TOKEN`

## Limitations & Warnings

- "There is a non-zero risk to workspace data by exposing it to LLMs"
- Certain operations deliberately restricted (e.g., no database deletion via MCP)
- **Deprecation Notice**: Notion prioritizes remote MCP server; this local repository may sunset, with reduced issue/PR monitoring

## Notable Features

- Tools optimized for token consumption by AI agents
- Markdown editing support for pages
- Automatic tool discovery—no manual updates needed when upgrading versions
- Backward compatibility note: No code changes required for upgrades; old tool names simply become unavailable

# Notion Product Capabilities Overview

## Core Features

**Pages & Content Organization**
Notion supports "Pages" as foundational units, with capabilities for "subpages" to create hierarchical structures. Users can "format your page" with various styling options and "customize and style your content."

**Databases**
The platform offers comprehensive database functionality including "Create a database" with multiple viewing and management options. Key database capabilities mentioned include "Views, filters, sorts & groups," "Database properties," "Relations & rollups," and "Database settings."

**Content Types Available**
- Wikis and verified pages ("Wikis & verified pages")
- Forms ("Use forms to collect, organize and act on responses")
- Knowledge bases ("Centralize your knowledge")
- Documentation systems
- Project management tools ("Manage any project")

## Database Views & Features

Multiple view types are available:
- Table, Board, Timeline, Calendar, List views
- Dashboards and Gallery views
- Chart view ("Use charts to visualize data and track progress")
- Feed and Map views
- Layout customization ("Build the perfect workflow with customizable layouts")

Advanced database capabilities:
- "Database templates" for standardized entry creation
- "Sub-items & dependencies" for task management
- "Task databases & sprints" functionality
- "Data sources and linked databases"
- Formulas ("How to write Notion formulas that extend the capabilities")

## Collaboration Features

- "Share your work" capabilities with granular permissions
- "Collaborate with people" with real-time editing
- Comments, mentions, and reactions functionality
- Reminders and notifications systems
- Page analytics ("Page analytics")
- Suggested edits workflow
- People Directory and profiles

## Automation & Workflow

- Button automations ("Buttons")
- Database button properties ("Make work more efficient with database button properties")
- Database automations triggering on conditions
- Webhook actions ("Share social media posts from Notion with webhook actions")
- Notification triggers ("Notify people instantly — with just a click")

## AI Capabilities

Notion integrates AI throughout:
- "Notion AI" for content generation and assistance
- "Notion Agent" for autonomous task handling
- "Custom Agents" for team automation ("Build Custom Agents that automate recurring workflows")
- AI Meeting Notes for transcription and summarization
- Enterprise Search powered by AI
- Research Mode for deep analysis
- Q&A functionality for workspace queries
- Auto-labeling for email organization

**Connectors**: AI integrates with external tools via connectors for Slack, Jira, Google Drive, GitHub, and others. "MCP lets Custom Agents securely connect to external tools."

## Content Blocks & Elements

Available block types include:
- Code blocks ("Code blocks")
- Math equations ("Math equations")
- Synced blocks ("Synced blocks")
- Images, files, and media ("Images, files & media")
- Links and backlinks ("Links & backlinks")
- Embeds and bookmarks ("Embeds, bookmarks & link mentions")

## Integration Ecosystem

- Notion API for custom integrations
- Pre-built integrations (GitHub, Slack, Jira, Asana, Monday.com)
- Email integration via Notion Mail
- Calendar integration via Notion Calendar
- Import capabilities from competing platforms

## Features with API Limitations

The help documentation suggests some features may have limited API support:
- Custom Agents and their configurations
- Real-time collaboration features
- Some AI-powered operations
- Certain automation workflows

## Enterprise & Security Features

- SAML SSO and SCIM provisioning
- Data retention settings ("Use Notion's Data Retention settings")
- Audit logging and workspace analytics
- IP restrictions and network control
- HIPAA configuration options

# Notion Database Query Details

## Status & Deprecation
This endpoint is **deprecated as of version 2025-09-03**. New implementations should use the "[Query a data source](/reference/query-a-data-source)" API instead.

## Filter Structure

### Compound Filters
The documentation supports two compound filter types:
- **"and"** filters: Multiple conditions that must all be satisfied
- **"or"** filters: At least one condition must be satisfied

These can be nested: "The set of filters chained by 'And' in the UI is equivalent to having each filter in the array of the compound 'and' filter."

### Single Filters
Databases can also be queried with single filters without compound operators.

## Supported Property Types
The documentation explicitly mentions:
- **Checkbox** properties (with `equals` operator)
- **Tags/Multi-select** properties (with `contains` operator)
- **Relations** properties
- **Formulas** and **Rollups**
- **Page timestamps**

## Sorting Capabilities
"Sorts operate on database properties or page timestamps and can be combined. The order of the sorts in the request matter, with earlier sorts taking precedence over later ones."

## Pagination
Results may contain fewer than `page_size` items. Use `next_cursor` values to iterate through paginated results.

## Query Limitations

### Formula & Rollup Constraints
- Relations with 25+ references: Only 25 evaluated in formulas
- Multi-layer relations may return incorrect results

### Property Filtering
The `filter_properties` query parameter narrows schema properties returned (supports multiple values).

## Permissions & Capabilities
- Requires database sharing with the integration
- Needs "read content" integration capabilities
- Missing access returns 404; insufficient permissions return 403

# Notion Database Property Types

| Property Type | Value Format | Read/Write | Limitations |
|---|---|---|---|
| **Title** | Array of rich text objects | Read-write | "maximum of 25 inline page or person references" |
| **Rich Text** | Array of rich text objects | Read-write | Limited to 25 page/person references in page retrieval |
| **Number** | Numeric value | Read-write | None documented |
| **Select** | Single option object with id/name/color | Read-write | Commas invalid in values; new options auto-created |
| **Status** | Single option object with id/name/color | Read-write | None documented |
| **Multi-select** | Array of option objects with id/name/color | Read-write | Commas invalid; new options auto-created if permitted |
| **Date** | Object with start, optional end, optional timezone | Read-write | ISO 8601 format required; timezone incompatible with UTC offsets |
| **Formula** | Object with type key + typed value (string/number/boolean/date) | Read-only | Subject to 25-reference limitation; values may not match UI |
| **Relation** | Array of page references with has_more flag | Read-write | Limited to 25 references; empty array clears relation |
| **Rollup** | Object with type, value, and function | Read-only | Subject to 25-reference limitation; values may not match UI |
| **People** | Array of user objects | Read-write | Limited to 25 people per property in standard retrieval |
| **Files** | Array of file objects with name property | Read-write | Notion-hosted files preserved; others overwritten completely |
| **Checkbox** | Boolean value | Read-write | None documented |
| **URL** | Non-empty string | Read-write | Must be valid web address format |
| **Email** | String value | Read-write | No structure enforced |
| **Phone Number** | String value | Read-write | No structure enforced |
| **Created Time** | ISO 8601 datetime string | Read-only | Cannot be updated after creation |
| **Created By** | User object | Read-only | Cannot be updated; identifies page creator |
| **Last Edited Time** | ISO 8601 datetime string | Read-only | Cannot be updated; automatically maintained |
| **Last Edited By** | User object | Read-only | Cannot be updated; identifies last modifier |

**Key Constraint:** All property values in page objects have "a 25 page reference limit" affecting certain property types during standard retrieval.

# Notion API Block Types Reference

## Complete Block Types Supported

### 1. **Audio**
- Represents audio files embedded in Notion pages
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: File object with type (external or file_upload); supports .mp3, .wav, .ogg, .oga, .m4a

### 2. **Bookmark**
- Represents saved links with captions
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: Caption array and URL required

### 3. **Breadcrumb**
- Navigation element showing page hierarchy
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: "Empty property object"

### 4. **Bulleted List Item**
- Individual item in unordered list
- Supports child blocks: Yes
- Can be created/updated: Yes
- Special properties: Rich text, color support, nested children capability

### 5. **Callout**
- Highlighted block with icon and message
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: Icon (emoji or file), rich text, color customization

### 6. **Child Database**
- Inline database within a page
- Supports child blocks: Yes
- Can be created/updated: "Use Create/Update database endpoints instead"
- Special properties: Title field only

### 7. **Child Page**
- Nested page within parent page
- Supports child blocks: Yes
- Can be created/updated: "Use Create/Update page endpoints instead"
- Special properties: Title field only

### 8. **Code**
- Syntax-highlighted code snippet
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: Language specification (40+ languages), caption, rich text

### 9. **Column**
- Container within column list
- Supports child blocks: Yes
- Can be created/updated: Yes
- Special properties: Width ratio (0-1) for relative sizing

### 10. **Column List**
- Parent container for columns
- Supports child blocks: Yes (only columns)
- Can be created/updated: Yes
- Special properties: "Must contain minimum two columns with children"

### 11. **Divider**
- Horizontal line separator
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: Empty property object

### 12. **Embed**
- External website content embedded
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: URL required; may not match UI appearance

### 13. **Equation**
- Mathematical expression
- Supports child blocks: No
- Can be created/updated: "Nested in rich text of paragraph blocks"
- Special properties: KaTeX-compatible expression string

### 14. **File**
- Document or data file attachment
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: Caption, type (file/external/file_upload), name field

### 15. **Heading 1**
- Large heading block
- Supports child blocks: "Yes, when is_toggleable is true"
- Can be created/updated: Yes
- Special properties: Rich text, color, toggleable option

### 16. **Heading 2**
- Medium heading block
- Supports child blocks: "Yes, when is_toggleable is true"
- Can be created/updated: Yes
- Special properties: Rich text, color, toggleable option

### 17. **Heading 3**
- Small heading block
- Supports child blocks: "Yes, when is_toggleable is true"
- Can be created/updated: Yes
- Special properties: Rich text, color, toggleable option

### 18. **Image**
- Visual image content
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: File object; supports .bmp, .gif, .heic, .jpeg, .jpg, .png, .svg, .tif, .tiff

### 19. **Link Preview**
- Rich preview of linked content
- Supports child blocks: No
- Can be created/updated: "Read-only; cannot create or append"
- Special properties: Original pasted URL only

### 20. **Meeting Notes**
- AI-generated meeting transcription and notes
- Supports child blocks: Yes
- Can be created/updated: "Read-only"
- Special properties: Title, status, child block pointers, calendar event metadata, recording window

### 21. **Mention**
- @-mention to user, date, page, database, or link preview
- Supports child blocks: No
- Can be created/updated: "Nested within rich text objects"
- Special properties: Type-specific object (database, date, link_preview, page, user)

### 22. **Numbered List Item**
- Individual item in ordered list
- Supports child blocks: Yes
- Can be created/updated: Yes
- Special properties: Rich text, color, list_start_index, list_format (numbers/letters/roman)

### 23. **Paragraph**
- Standard text block
- Supports child blocks: Yes
- Can be created/updated: Yes
- Special properties: Rich text, color support

### 24. **PDF**
- Embedded PDF document
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: File object, caption, supports only .pdf type

### 25. **Quote**
- Indented quoted text
- Supports child blocks: Yes
- Can be created/updated: Yes
- Special properties: Rich text, color, nested children

### 26. **Synced Block**
- Content synchronized across multiple locations
- Supports child blocks: Yes
- Can be created/updated: "Cannot update content after creation"
- Special properties: Original blocks reference via synced_from null; duplicates reference original block ID

### 27. **Table**
- Tabular data grid
- Supports child blocks: Yes (table rows only)
- Can be created/updated: "table_width cannot change after creation"
- Special properties: table_width, has_column_header, has_row_header

### 28. **Table of Contents**
- Auto-generated page outline
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: Color customization only

### 29. **Template**
- Reusable block template button
- Supports child blocks: Yes
- Can be created/updated: "Deprecated as of March 27, 2023"
- Special properties: Rich text title, duplicated children on use

### 30. **To Do**
- Checkbox task item
- Supports child blocks: Yes
- Can be created/updated: Yes
- Special properties: Rich text, checked status, color, nested children

### 31. **Toggle**
- Collapsible/expandable block
- Supports child blocks: Yes
- Can be created/updated: Yes
- Special properties: Rich text, color, nested children

### 32. **Transcription**
- Legacy meeting notes format
- Supports child blocks: Yes
- Can be created/updated: "Read-only; renamed to meeting_notes in API v2026-03-11"
- Special properties: Same as meeting_notes

### 33. **Unsupported**
- Placeholder for unimplemented block types
- Supports child blocks: No
- Can be created/updated: No
- Special properties: Contains block_type field identifying actual type (form, button, etc.)

### 34. **Video**
- Embedded video content
- Supports child blocks: No
- Can be created/updated: Yes
- Special properties: File object; supports multiple platforms including Vimeo

---

## Key Limitations Summary
- API does not support "all block types" present in Notion UI
- Some blocks are read-only (link_preview, meeting_notes, transcription)
- Certain blocks require special endpoints (child_database, child_page)
- table_width is immutable after creation
- Template blocks deprecated for creation

# Notion API Limits - Complete Summary

## Rate Limits

**Requests per second:** "an average of three requests per second" with allowances for brief bursts beyond this threshold.

**Error handling:** Rate-limited requests return a 429 HTTP status with a `"rate_limited"` error code.

**Retry mechanism:** The API includes a `Retry-After` response header specifying the minimum wait time in seconds before retrying. Developers should respect this value and wait the indicated duration before resubmitting requests.

**Future changes:** Notion reserves the right to adjust rate limits based on demand and reliability needs, potentially introducing distinct limits for different pricing tiers.

## Payload Size Limits

- **Overall maximum:** 500KB per request
- **Block elements:** Maximum of 1000 block elements per payload

## Property Value Limits

| Type | Limit |
|------|-------|
| Rich text content | 2,000 characters |
| Text links (URLs) | 2,000 characters |
| Equation expressions | 1,000 characters |
| Any URL | 2,000 characters |
| Email addresses | 200 characters |
| Phone numbers | 200 characters |
| Multi-select options | 100 options |
| Relations | 100 related pages |
| People mentions | 100 users |
| Block arrays | 100 elements |

## Error Handling

Size violations trigger a 400 HTTP status with a `"validation_error"` code and detailed error messaging for debugging.

# Notion API Authentication & Authorization Details

## 1. Internal Integration Tokens

**Token Type & Usage:**
Internal integrations use a single static token tied to a specific workspace. The token must be included in the `Authorization` header as `Bearer {INTEGRATION_TOKEN}` for every API request.

**Retrieval:**
Tokens are obtained from the integration's Configuration tab in the integrations dashboard. Only workspace owners can create internal integrations.

**Security:**
"Keep your token secret... never store the token in your source code or commit it in version control. Instead, read the token from an environment variable."

## 2. Public OAuth 2.0 Flow

The public integration authorization follows a six-step process:

**Step 1 - Authorization URL:**
Users navigate to a Notion authorization endpoint with parameters: `client_id`, `redirect_uri`, `response_type` (always `code`), `owner` (always `user`), and optional `state` for CSRF protection.

**Step 2 - Authorization Code:**
After user consent, Notion redirects to the specified `redirect_uri` with a temporary `code` query parameter.

**Step 3 - Token Exchange:**
The integration sends a POST request to `https://api.notion.com/v1/oauth/token` using HTTP Basic Authentication (base64-encoded `CLIENT_ID:CLIENT_SECRET`). Body includes: `grant_type: "authorization_code"`, temporary `code`, and `redirect_uri`.

**Step 4 - Token Response:**
Notion returns: `access_token`, `refresh_token`, `bot_id`, `workspace_id`, `workspace_name`, `workspace_icon`, and optional `duplicated_template_id`.

**Step 5 - Token Storage:**
Both tokens should be stored in a database with relationships to accessed Notion resources, using `bot_id` as the primary key.

**Step 6 - Token Refresh:**
POST requests to the token endpoint with `grant_type: "refresh_token"` and the stored refresh token generate new access and refresh tokens.

## 3. Token Formats

**Access Token:** String used to authorize subsequent API requests in the `Authorization` header.

**Refresh Token:** String prefixed with `nrt_` (example: "nrt_4991090011501Ejc6Xn4sHguI7jZIN449mKe9PRhpMfNK").

**Bot ID:** Unique identifier returned with tokens, serving as the primary key for token storage.

## 4. Scopes and Permissions

The documentation does not explicitly define granular OAuth scopes. Instead, it mentions "capabilities" presented to users during authorization—what the integration can do in the workspace.

**Permission Mechanisms:**
- Internal integrations require manual page/database sharing through the Notion UI ("Add connections")
- Public integrations use a page picker interface allowing users to select specific pages and databases
- Parent pages grant access to all child pages
- Users must have full access to resources to share them with integrations

## 5. Access to Pages/Databases

**Internal Integrations:**
Pages must be manually shared via the workspace interface. The integration cannot access unshared pages; requests return errors.

**Public Integrations:**
Users grant access during the OAuth flow through a page picker interface. Access is determined by user selections during authorization or template duplication.

**Important Note:**
"After a user installs a public integration, only that user is able to interact or share pages and databases with the integration."

## 6. Token Expiration & Refresh

The document does not specify access token expiration times. However, it emphasizes that "refreshing an access token will generate a new access token and a new refresh token."

Refresh tokens are stored for "ongoing token lifecycle support."

## 7. Security Considerations

- Tokens must not be stored in source code or version control
- Use environment variables or secret managers for token storage
- HTTP Basic Authentication requires base64 encoding of credentials
- The `state` parameter prevents CSRF attacks
- Error handling should gracefully manage authorization failures (e.g., `access_denied`, `invalid_grant`)
- Store all received token information including workspace metadata for future product changes

# Notion Search API: Complete Details

## Searchable Objects

The API searches across **pages and data sources** shared with an integration. "Searches all parent or child pages and data_sources that have been shared with an integration." Duplicated linked databases are excluded from results.

## Query Syntax

The `query` parameter accepts a string for title-based searching. Omitting the query parameter returns all accessible pages or data sources without filtering.

## Filter Options

A single `filter` parameter limits results:
- **Property**: Must be `"object"`
- **Values**: `"page"` (pages only) or `"data_source"` (data sources only)

Without filtering, both types appear in results.

## Sort Options

Results support one sorting method:
- **Timestamp field**: `last_edited_time`
- **Direction**: `ascending` or `descending`

Sorting is optional.

## Pagination

The endpoint supports pagination with:
- `start_cursor` (UUID format) for position tracking
- `page_size` for result count per request
- `has_more` (boolean) and `next_cursor` in responses indicate additional pages

## Result Format

Responses contain:
- Array of `results` (pages and/or data sources)
- `object: "list"` wrapper
- `next_cursor` and `has_more` for pagination
- Mixed page types: full `pageObjectResponse` or minimal `partialPageObjectResponse`
- Data source variants similarly included

## Key Limitations & Gotchas

1. **Title-only searching**: "Returns all pages or data_sources...that have titles that include the query param"—content within pages isn't searched

2. **Integration scope**: Results reflect only what the integration can access; "The results adhere to any limitations related to an integration's capabilities"

3. **Data source specificity**: For searching within a single data source (not all shared sources), "use the Query a data_source endpoint instead"

4. **API versioning**: Requires `Notion-Version` header; current version is `2026-03-11`

5. **Error handling**: Returns standard HTTP status codes (400, 401, 403, 404, 429, 500, 503) with descriptive error objects

# Notion SDK for JavaScript - Overview

## 1. Supported Operations

The SDK provides access to Notion API endpoints through pre-built method families:

- **Pages & Data Sources**: Query, create, and update pages and data sources
- **Blocks**: List, retrieve, and manage block children
- **Databases**: Interact with database structures
- **Users**: List and retrieve user information
- **Comments**: Create and manage comments
- **Custom Requests**: Direct endpoint access via `notion.request()` for newer API features

Per the documentation: "Endpoint parameters are grouped into a single object. You don't need to remember which parameters go in the path, query, or body."

## 2. Installation & Setup

**Installation:** `npm install @notionhq/client`

**Basic initialization:**
```javascript
const { Client } = require("@notionhq/client");
const notion = new Client({ auth: process.env.NOTION_TOKEN });
```

Supports both integration tokens and OAuth access tokens.

## 3. Key Features

- **Type-safe responses** with TypeScript definitions included
- **Error handling** with `APIErrorCode` and `ClientErrorCode` enums for type-safe error management
- **Automatic retries** (default: 2 attempts) for rate limits (429) and transient server errors (500, 503)
- **Pagination utilities**: `iteratePaginatedAPI()` and `collectPaginatedAPI()` for managing paginated results
- **Type guards** like `isFullPage()`, `isFullBlock()` to distinguish full vs. partial responses
- **Configurable logging** with `LogLevel.DEBUG` for debugging
- **Custom HTTP agent** support for proxy scenarios

## 4. Version Information

- **Runtime requirement**: Node.js ≥ 18
- **TypeScript**: ≥ 5.9 (optional)
- **API versions supported**: 2025-09-03 (default) and 2026-03-11
- **Minimum API version**: Depends on SDK version; v5.0.0+ requires 2025-09-03

## 5. Limitations & Notable Patterns

- Server errors (500, 503) are only retried for idempotent methods (GET, DELETE) to prevent duplicate side effects
- Rate limits (429) are retried for all HTTP methods
- Exponential backoff with jitter prevents thundering herd problems
- Custom `fetch` function can be provided for non-standard environments
- For large paginated datasets, use `iteratePaginatedAPI()` rather than `collectPaginatedAPI()` to avoid memory issues

# Notion Users API Overview

## Supported Operations

Only **one operation** is documented: listing all users in a workspace via `GET /v1/users`. The documentation mentions a "User" reference but does not detail individual retrieval endpoints.

## User Fields Available

Each user object contains:
- **id**: UUID identifier
- **object**: Always "user"
- **name**: String or null
- **avatar_url**: String or null
- **type**: Either "person" or "bot"

For person users, an additional field includes:
- **person.email**: The user's email address

For bot users, an optional field provides:
- **bot**: Owner details, workspace information, and upload size limits

## User Types

**Person users** represent actual workspace members with email addresses. **Bot users** are integrations, owned either by a specific person or the entire workspace. Bot objects include workspace ID, workspace name, and file upload size restrictions.

## Key Limitations

"The API does not currently support filtering users by their email and/or name." Guest accounts are excluded from responses. The endpoint requires integration capabilities for user information access; calls without proper permissions return HTTP 403. Responses are paginated using cursor-based navigation.

# Notion API Database Creation: Comprehensive Details

## Deprecation Notice
This endpoint is **deprecated as of version 2025-09-03**. The API split database and data source concepts. Use the newer `/reference/database-create` and `/reference/create-a-data-source` endpoints instead.

## Supported Property Types

The API supports 27 property types for initial data source configuration:

- **Basic Fields**: title, rich_text, url, email, phone_number
- **Numeric**: number (with format options)
- **Selection**: select, multi_select, status
- **Date/Time**: date, created_time, last_edited_time, last_visited_time
- **Relationships**: relation, rollup
- **Metadata**: created_by, last_edited_by, unique_id
- **Files**: files
- **People**: people
- **Advanced**: formula, button, location, verification, place

## Schema Format

Each property requires:
- `type`: property type identifier (e.g., "text", "select")
- Type-specific configuration object
- Optional `description` field (max 280 characters)

Example structure for a select property:
```
"select": {
  "options": [
    { "name": "Option", "color": "blue", "description": null }
  ]
}
```

## Parent Requirements

Parents must be one of two types:

1. **page_id**: "The parent of a new database must be a Notion page or a wiki database"
2. **workspace**: Boolean flag set to `true`

The API returns 404 if parent doesn't exist or integration lacks access.

## Limitations vs UI Creation

- **Status properties cannot be created via API**: "Creating new `status` database properties is currently not supported"
- **Integration capabilities required**: Endpoint demands insert content capabilities (403 error otherwise)
- **Request rate limits apply**: Exceeding limits returns 429 response

## Additional Configuration Options

- **Title & description**: Rich text arrays (max 100 items each)
- **is_inline**: Boolean for inline display (defaults false)
- **Icon & cover**: Supports emoji, external URLs, or file uploads
- **initial_data_source**: Optional configuration object for data source setup

# API Database Working Guide: Key Details

## Property Type Configurations

The documentation describes property objects with type-specific data patterns. For the **number** type, configuration includes a `format` field (example shows `"dollar"`). The **date** type supports conditions like `"past_week"`. However, the provided content offers limited detail on formula syntax, relation types, or rollup function specifications beyond these examples.

## Database Views

The documentation makes no mention of view management capabilities through the API. This represents a significant gap—while the UI clearly supports database views, there's no evidence that the API exposes endpoints for creating, modifying, or retrieving views.

## Filter Capabilities

Single property filters use the pattern: `"property": [name], [type]: [condition]`. The documentation provides one concrete example: date filters support conditions like `"past_week": {}`

The guide also mentions "compound filters" that combine conditions using "and" or "or" operators, but specifics for each property type aren't detailed in this excerpt.

## UI-API Capability Gaps

Several notable limitations exist:

- **Linked databases**: "Notion's API does not currently support linked data sources"
- **Wiki databases**: Creation only possible through the workspace UI, not via API
- **Schema limits**: Recommendation states a maximum of "50KB" for database schemas
- **Database views**: No API support documented

The documentation acknowledges these constraints exist but doesn't provide comprehensive coverage of all property-specific filter conditions or advanced configuration options.

{
  "file_path": "~/dev/audits/notion-universal-baseline-2026-03-13-opus/research/notion-api-capabilities.md",
  "content": "# Notion API Capabilities Research\n\n**Date:** 2026-03-13\n**API Version:** 2026-03-11 (latest), 2025-09-03 (previous)\n**Base URL:** https://api.notion.com\n\n---\n\n## 1. Core Object Model\n\nNotion's data model is built on four primary object types:\n\n### Pages\n- The fundamental content unit. Every piece of content lives on a page.\n- Pages have **properties** (when inside a database/data source) and **content** (a tree of blocks).\n- Pages can be nested (child pages) or live inside databases.\n- Operations: Create, Retrieve, Update (archive/unarchive), Search.\n- New: Pages can be retrieved and updated as **Notion-flavored Markdown** via `/v1/pages/:id/markdown` (GET/PATCH).\n\n### Data Sources (formerly Databases)\n- Structured collections of pages with a defined schema of property columns.\n- As of API version 2025-09-03, Notion split the concept of \"database\" into **database** (metadata/schema container) and **data source** (queryable view of data). The data source is now the primary interface.\n- Operations: Create, Retrieve, Update schema, Query (with filters/sorts).\n- Templates can be listed and applied when creating pages.\n\n### Blocks\n- The atomic content units inside pages. Pages themselves are blocks.\n- Blocks form a tree structure (blocks can have children).\n- Operations: Retrieve, List children, Append children, Update, Delete.\n- 34 block types documented (see Section 4).\n\n### Users\n- Person users (workspace members) and Bot users (integrations).\n- Operations: List all, Retrieve by ID, Retrieve bot user (self).\n- Limitation: Cannot filter by email or name. Guest users excluded from list.\n\n### Other Objects\n- **Comments**: Create and list comments on pages and blocks.\n- **File Uploads**: Upload files (single-part up to 20MB, multi-part up to 5GB).\n- **Search**: Search across all shared pages and data sources by title.\n\n---\n\n## 2. Authentication Model\n\n### Internal Integrations\n- Static token per workspace (format: `ntn_****`).\n- Created by workspace owners at notion.so/profile/integrations.\n- Pages/databases must be explicitly shared with the integration via the UI (\"Add connections\").\n- Token never expires but should be stored securely (env vars, not source code).\n\n### Public Integrations (OAuth 2.0)\n- Standard OAuth 2.0 authorization code flow.\n- Six-step process: redirect to Notion -> user grants access via page picker -> authorization code -> token exchange -> store tokens -> refresh.\n- Refresh tokens prefixed with `nrt_`.\n- Access granted only to pages the installing user selects during OAuth.\n- Only the installing user can share additional pages with the integration.\n\n### Required Headers\n```\nAuthorization: Bearer <token>\nNotion-Version: 2026-03-11\nContent-Type: application/json\n```\n\n---\n\n## 3. Database Property Types (20 types)\n\n| Property Type | Read/Write | Key Constraints |\n|---|---|---|\n| **Title** | R/W | Max 25 inline page/person references |\n| **Rich Text** | R/W | Max 2,000 characters |\n| **Number** | R/W | Configurable format (number, dollar, percent, etc.) |\n| **Select** | R/W | Commas invalid in option names; new options auto-created |\n| **Multi-select** | R/W | Max 100 options; commas invalid |\n| **Status** | R/W (values only) | **Cannot create new status properties via API** |\n| **Date** | R/W | ISO 8601; optional end date and timezone |\n| **Checkbox** | R/W | Boolean |\n| **URL** | R/W | Max 2,000 characters |\n| **Email** | R/W | Max 200 characters |\n| **Phone Number** | R/W | Max 200 characters |\n| **Files** | R/W | Notion-hosted files preserved; external overwritten |\n| **People** | R/W | Max 100 users |\n| **Relation** | R/W | Max 100 related pages; 25 evaluated in formulas |\n| **Rollup** | **Read-only** | Subject to 25-reference limit; may not match UI |\n| **Formula** | **Read-only** | Subject to 25-reference limit; may not match UI |\n| **Created Time** | **Read-only** | Auto-set |\n| **Created By** | **Read-only** | Auto-set |\n| **Last Edited Time** | **Read-only** | Auto-set |\n| **Last Edited By** | **Read-only** | Auto-set |\n\nAdditional schema-level types: `unique_id`, `button`, `location`, `verification`, `place`.\n\n---\n\n## 4. Block Types (34 types)\n\n### Fully Creatable/Updatable via API\n- **Text**: Paragraph, Heading 1/2/3 (with optional toggle), Bulleted List Item, Numbered List Item, To Do, Quote, Callout, Toggle\n- **Media**: Image (.bmp/.gif/.heic/.jpeg/.jpg/.png/.svg/.tif/.tiff), Video, Audio (.mp3/.wav/.ogg/.m4a), File, PDF\n- **Structure**: Divider, Column List, Column (with width ratio), Table (with rows), Breadcrumb, Table of Contents\n- **Embeds**: Bookmark, Embed, Code (40+ languages)\n- **Advanced**: Equation (KaTeX), Synced Block (content immutable after creation)\n- **References**: Child Page, Child Database (use page/database create endpoints)\n\n### Read-Only (cannot create via API)\n- **Link Preview**: Rich preview of pasted URLs\n- **Meeting Notes**: AI-generated meeting transcription (new in 2026-03-11)\n\n### Deprecated\n- **Template Block**: Deprecated March 2023 (use database templates instead)\n\n### Unsupported (exist in UI only)\n- **Forms**, **Buttons** (automation), **Simple Tables** (some variants), and other UI-specific blocks return as `\"unsupported\"` type with a `block_type` hint field.\n\n---\n\n## 5. Query, Filter & Sort Capabilities\n\n### Database/Data Source Querying\n- **Compound Filters**: `and` (all conditions match) and `or` (any condition matches), nestable.\n- **Single Property Filters**: Each property type has its own filter operators.\n- **Sorts**: On any property or `created_time`/`last_edited_time`. Multiple sorts supported (earlier sorts take precedence).\n- **Pagination**: `page_size` (max 100), `start_cursor` for cursor-based pagination.\n- **filter_properties**: Narrows which properties are returned in results.\n\n### Search API\n- **Scope**: Searches titles only (not page content) across all shared pages and data sources.\n- **Filter**: By object type (`page` or `data_source`).\n- **Sort**: By `last_edited_time` (ascending/descending).\n- **Limitation**: Title-only search; for content search within a database, use Query endpoint with filters.\n\n### Key Query Limitations\n- Relations with 25+ references: only 25 evaluated in formulas/rollups.\n- Multi-layer relations may return incorrect results.\n- Search does not index page body content.\n\n---\n\n## 6. Rate Limits & Size Constraints\n\n### Rate Limits\n- **Average 3 requests per second** per integration (brief bursts allowed).\n- HTTP 429 returned when exceeded, with `Retry-After` header (seconds to wait).\n- Notion reserves right to adjust limits by pricing tier.\n\n### Payload Limits\n- **Request body**: Max 500KB.\n- **Blocks per request**: Max 1,000 block elements.\n- **Rich text**: Max 2,000 characters per property value.\n- **Equation expressions**: Max 1,000 characters.\n- **URLs**: Max 2,000 characters.\n- **Emails/Phone numbers**: Max 200 characters.\n- **Multi-select options**: Max 100 per property.\n- **Relations**: Max 100 per property.\n- **People**: Max 100 per property.\n- **Block arrays**: Max 100 elements per append.\n- **Database schema**: Recommended max 50KB.\n\n### File Limits\n- **Free workspaces**: 5MB per file.\n- **Paid workspaces**: 5GB per file.\n- **Multi-part uploads**: Up to 5GB total; each part 5-20MB (final part < 5MB).\n- **File URLs expire after 1 hour** (must re-fetch).\n\n### Pagination\n- Default and maximum page size: 100 items.\n- Cursor-based with `start_cursor` / `next_cursor` / `has_more`.\n\n---\n\n## 7. API Endpoints Summary\n\n### Pages\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/v1/pages` | Create a page (with properties, content, template) |\n| GET | `/v1/pages/:id` | Retrieve page metadata and properties |\n| PATCH | `/v1/pages/:id` | Update page properties, archive/unarchive |\n| GET | `/v1/pages/:id/markdown` | Get page content as Markdown |\n| PATCH | `/v1/pages/:id/markdown` | Update page content via Markdown |\n\n### Data Sources\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/v1/data_sources/:id` | Create a data source |\n| PATCH | `/v1/data_sources` | Update data source schema |\n| POST | `/v1/data_sources/:id/query` | Query with filters and sorts |\n| GET | `/v1/data_sources/:id/templates` | List templates |\n\n### Blocks\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/v1/blocks/:id` | Retrieve a block |\n| GET | `/v1/blocks/:id/children` | List child blocks (paginated) |\n| PATCH | `/v1/blocks/:id/children` | Append child blocks |\n| PATCH | `/v1/blocks/:id` | Update a block |\n| DELETE | `/v1/blocks/:id` | Delete (archive) a block |\n\n### Users\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/v1/users` | List all users (paginated) |\n| GET | `/v1/users/:id` | Retrieve a user |\n| GET | `/v1/users/me` | Retrieve the bot user |\n\n### Comments\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/v1/comments` | Create a comment |\n| GET | `/v1/comments?block_id=` | List comments on a block |\n\n### Search\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/v1/search` | Search pages and data sources by title |\n\n### File Uploads\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/v1/file_uploads` | Create upload (single/multi-part/external URL) |\n| GET | `/v1/file_uploads/:id` | Retrieve upload status |\n| POST | `/v1/file_uploads/:id/send` | Send file parts |\n| POST | `/v1/file_uploads/:id/complete` | Complete multi-part upload |\n\n---\n\n## 8. Agent-Oriented Interfaces\n\n### Official MCP Server (`@notionhq/notion-mcp-server`)\n- **22 tools** exposed to AI agents via Model Context Protocol.\n- Key tools: query-data-source, create/retrieve/update pages, move-page, search, create/retrieve comments, list-data-source-templates.\n- Supports **Markdown page editing** for efficient content manipulation.\n- Auth via `NOTION_TOKEN` environment variable.\n- Transport: STDIO (default) or Streamable HTTP (port 3000).\n- Available via npm (`npx @notionhq/notion-mcp-server`) or Docker (`mcp/notion`).\n- **Deprecation warning**: Notion is prioritizing a remote MCP server; the local npm package may sunset.\n- Install: `npm install @notionhq/notion-mcp-server` or configure in Claude Desktop / Cursor.\n\n### Official JavaScript/TypeScript SDK (`@notionhq/client`)\n- Full API coverage with type-safe responses.\n- Automatic retries (429s and 5xx for idempotent methods).\n- Pagination utilities: `iteratePaginatedAPI()`, `collectPaginatedAPI()`.\n- Type guards: `isFullPage()`, `isFullBlock()`, etc.\n- Node.js >= 18, TypeScript >= 5.9.\n- `notion.request()` for direct endpoint access.\n\n### Custom Agents (Notion Product Feature)\n- Notion has a built-in \"Custom Agents\" feature in the product UI.\n- Agents can connect to external tools via MCP.\n- Integration with Cursor IDE for automated PR creation from Notion tasks.\n- MCP allowlist management in workspace settings.\n\n### No Official CLI Tool\n- No standalone Notion CLI was found in the makenotion GitHub organization.\n\n---\n\n## 9. Notion-Flavored Markdown Support\n\nThe API supports a custom Markdown dialect for page content:\n\n### Standard Markdown\n- Bold, italic, strikethrough, inline code, links, headings (H1-H4; H5/H6 downgraded to H4), bulleted/numbered lists, to-dos, quotes, code blocks with language, equations, tables, dividers.\n\n### Notion Extensions\n- **Mentions**: `<mention-user>`, `<mention-page>`, `<mention-database>`, `<mention-date>` with custom HTML-like tags.\n- **Callouts**: `<callout icon=\"emoji\" color=\"Color\">content</callout>`.\n- **Toggles**: `<details>` or heading with `{toggle=\"true\"}`.\n- **Columns**: `<columns><column>...</column></columns>`.\n- **Synced blocks**: `<synced_block url=\"...\">` and `<synced_block_reference url=\"...\">`.\n- **Database references**: `<database url=\"...\" inline=\"true|false\">`.\n- **Colors**: 10 text colors + 10 background colors (append `_bg`).\n- **Underline**: `<span underline=\"true\">text</span>`.\n- **Citations**: `[^URL]`.\n\n---\n\n## 10. Gaps: UI vs API Capabilities\n\n| Feature | UI | API | Notes |\n|---------|-----|------|-------|\n| **Database views** (table, board, timeline, calendar, gallery, chart, map) | Yes | **No** | Cannot create, read, or manage views |\n| **Linked databases** | Yes | **No** | Cannot create linked database views |\n| **Wiki databases** | Yes | **No** | Cannot create wiki databases |\n| **Status property creation** | Yes | **No** | Can only read/write existing status values |\n| **Forms** | Yes | **No** | Blocks render as \"unsupported\" |\n| **Buttons/Automations** | Yes | **No** | Blocks render as \"unsupported\" |\n| **Database automations** | Yes | **No** | No API for automation rules |\n| **Page analytics** | Yes | **No** | No API access |\n| **AI features** (summaries, Q&A, auto-fill) | Yes | **No** | No API for Notion AI |\n| **Charts** | Yes | **No** | No API for chart views |\n| **Suggested edits** | Yes | **No** | No API |\n| **Permissions management** | Yes | **Limited** | Cannot set page permissions via API (only share with integration) |\n| **Full-text content search** | Yes | **No** | API search is title-only |\n| **Trash/restore** | Yes | **Partial** | Can archive/unarchive but not permanently delete or access trash |\n| **Template blocks** | Deprecated | **Deprecated** | Use database templates instead |\n| **Synced block editing** | Yes | **No** | Can create but not update synced block content |\n| **Table width changes** | Yes | **No** | `table_width` immutable after creation |\n| **Meeting notes** | Yes | **Read-only** | Cannot create via API |\n| **Link previews** | Yes | **Read-only** | Cannot create via API |\n| **Notion Mail** | Yes | **No** | No API |\n| **Notion Calendar** | Yes | **No** | No API |\n\n---\n\n## 11. Key Gotchas and Limitations\n\n1. **3 req/sec rate limit** is quite low for bulk operations. Plan for throttling.\n2. **File URLs expire after 1 hour**. Never cache them; always re-fetch.\n3. **25-reference limit** on relations evaluated in formulas/rollups. Large relation sets may produce incorrect formula results.\n4. **Search is title-only**. For content search, you must query each database individually with filters.\n5. **Template application is async**. Page returns blank immediately; must poll or use webhooks to confirm content population.\n6. **No view management**. Cannot programmatically create filtered/sorted views, board views, calendar views, etc.\n7. **Rich text max 2,000 chars** per property. For longer content, use page body blocks.\n8. **500KB request limit**. Large page creates/updates must be chunked.\n9. **Max 100 blocks per append**. Building large pages requires multiple requests.\n10. **Data source vs database split** (API 2025-09-03+). Old `database_id` patterns must migrate to `data_source_id`.\n11. **Integration access is explicit**. Every page/database must be manually shared with the integration - no workspace-wide access for internal integrations.\n12. **Guest users invisible** to the Users API.\n13. **Cannot delete databases** via API (or MCP).\n14. **No bulk operations**. Each page create/update is a separate API call.\n15. **Pagination max 100 items**. Retrieving large datasets requires many sequential requests at 3 req/sec.\n16. **OAuth tokens**: Only the installing user can share additional pages. Other workspace members cannot expand access.\n\n---\n\n## 12. Enterprise & Security Features\n\n- **Audit logging**: Full event logging (37 page event types, 9 database events, 90+ workspace events).\n- **SIEM integration**: Real-time webhook-based security monitoring.\n- **SAML SSO / SCIM**: Full identity provider integration.\n- **Encryption**: WEK/DEK/CMK key management with rotation support.\n- **Legal holds**: Organization-level data preservation.\n- **Data retention**: Configurable trash/purge delays.\n- **IP allowlisting**: Network-level access control.\n- **MCP allowlisting**: Control which MCP clients can connect.\n\n---\n\n## 13. Sources\n\n| Resource | URL | Status |\n|----------|-----|--------|\n| Machine-readable docs | https://developers.notion.com/llms-full.txt | Fetched successfully |\n| API Reference | https://developers.notion.com/reference | Fetched successfully |\n| API Docs overview | https://developers.notion.com/docs | 404 (content covered by other pages) |\n| Help/Guides | https://www.notion.com/help/guides | Fetched (redirected from notion.so) |\n| MCP Server README | github.com/makenotion/notion-mcp-server | Fetched successfully |\n| JS SDK | github.com/makenotion/notion-sdk-js | Fetched successfully |\n| Rate limits | developers.notion.com/reference/request-limits | Fetched successfully |\n| Authentication | developers.notion.com/docs/authorization | Fetched successfully |\n| Block types | developers.notion.com/reference/block | Fetched successfully |\n| Property types | developers.notion.com/reference/property-value-object | Fetched successfully |\n| Search API | developers.notion.com/reference/post-search | Fetched successfully |\n| Database creation | developers.notion.com/reference/create-a-database | Fetched successfully |\n| Database querying | developers.notion.com/reference/post-database-query | Fetched successfully |\n| Working with databases | developers.notion.com/docs/working-with-databases | Fetched successfully |\n| Users API | developers.notion.com/reference/get-users | Fetched successfully |\n"
}

{
  "url": "https://developers.notion.com/reference/create-a-database",
  "prompt": "Extract the FULL API reference for creating a database. I need to know:\n1. What are all the parameters for the Create Database endpoint?\n2. Is there a `properties` parameter? If so, what does it look like?\n3. Is there an `initial_data_source` parameter? If so, what does it look like and how is it used?\n4. Show me any example request/response bodies in full.\n5. How do you specify property schemas (like Select, Date, Number) when creating a database?\nGive me ALL the details, code examples, and JSON structures shown on this page."
}

~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.d.ts
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/Client.d.ts
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/errors.d.ts
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/fetch-types.d.ts
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/helpers.d.ts
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/index.d.ts
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/logging.d.ts
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/type-utils.d.ts
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/utils.d.ts

# Create Database API Reference

## Endpoint Parameters

The POST `/v1/databases` endpoint accepts these parameters:

**Required:**
- `parent` (object): Where the database will be created - either a page or workspace
- `Notion-Version` (header): API version (current: `2026-03-11`)

**Optional:**
- `title` (array of rich text items, max 100 items)
- `description` (array of rich text items, max 100 items)
- `is_inline` (boolean): Display inline in parent page (defaults to false)
- `initial_data_source` (object): Initial data source configuration
- `icon` (object): Database icon
- `cover` (object): Cover image

## Parent Parameter Format

Two options:

```json
{
  "type": "page_id",
  "page_id": "b55c9c91-384d-452b-81db-d1ef79372b75"
}
```

Or:

```json
{
  "type": "workspace",
  "workspace": true
}
```

## Initial Data Source Parameter

The `initial_data_source` contains the property schema:

```json
{
  "initial_data_source": {
    "properties": {
      "property_name": {
        "type": "property_type",
        ...configuration...
      }
    }
  }
}
```

## Property Type Examples

**Title:**
```json
{
  "type": "title",
  "title": {}
}
```

**Select:**
```json
{
  "type": "select",
  "select": {
    "options": [
      {
        "name": "Option 1",
        "color": "blue",
        "description": "Optional description"
      }
    ]
  }
}
```

**Multi-Select:**
```json
{
  "type": "multi_select",
  "multi_select": {
    "options": [
      {
        "name": "Tag 1",
        "color": "red"
      }
    ]
  }
}
```

**Number:**
```json
{
  "type": "number",
  "number": {
    "format": "number"
  }
}
```

**Date:**
```json
{
  "type": "date",
  "date": {}
}
```

**Relation:**
```json
{
  "type": "relation",
  "relation": {
    "data_source_id": "source-id",
    "type": "single_property",
    "single_property": {}
  }
}
```

**Other supported types:** rich_text, url, email, phone_number, checkbox, people, files, created_by, created_time, last_edited_by, last_edited_time, formula, rollup, unique_id, button, location, verification, last_visited_time, place.

## Example Request (TypeScript SDK)

```javascript
import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.databases.create({
  parent: {
    type: "page_id",
    page_id: "b55c9c91-384d-452b-81db-d1ef79372b75"
  },
  title: [{ text: { content: "My Database" } }]
})
```

## Response Format

Success returns HTTP 200 with either `partialDatabaseObjectResponse` or `databaseObjectResponse`:

```json
{
  "object": "database",
  "id": "uuid",
  "title": [...],
  "description": [...],
  "parent": {...},
  "is_inline": false,
  "in_trash": false,
  "is_locked": false,
  "created_time": "2024-01-01T00:00:00.000Z",
  "last_edited_time": "2024-01-01T00:00:00.000Z",
  "data_sources": [...],
  "icon": null,
  "cover": null,
  "url": "https://...",
  "public_url": null
}
```

## Key Limitations

- "Creating new `status` database properties is currently not supported"
- Requires integration to have insert content capabilities
- Parent must be a Notion page or wiki database

     1→{
     2→  "name": "@notionhq/client",
     3→  "version": "5.12.0",
     4→  "description": "A simple and easy to use client for the Notion API",
     5→  "engines": {
     6→    "node": ">=18"
     7→  },
     8→  "homepage": "https://developers.notion.com/docs/getting-started",
     9→  "bugs": {
    10→    "url": "https://github.com/makenotion/notion-sdk-js/issues"
    11→  },
    12→  "repository": {
    13→    "type": "git",
    14→    "url": "https://github.com/makenotion/notion-sdk-js/"
    15→  },
    16→  "keywords": [
    17→    "notion",
    18→    "notionapi",
    19→    "rest",
    20→    "notion-api"

node_modules/@notionhq/client/build/src/api-endpoints.js-301-    bodyParams: [
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.js-302-        "parent",
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.js-303-        "title",
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.js-304-        "description",
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.js-305-        "is_inline",
node_modules/@notionhq/client/build/src/api-endpoints.js:306:        "initial_data_source",
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.js-307-        "icon",
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.js-308-        "cover",
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.js-309-    ],
node_modules/@notionhq/client/build/src/api-endpoints.js-310-    path: () => `databases`,
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.js-311-};
--
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3748-        workspace: true;
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3749-    });
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3750-    title?: Array<RichTextItemRequest>;
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3751-    description?: Array<RichTextItemRequest>;
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3752-    is_inline?: boolean;
node_modules/@notionhq/client/build/src/api-endpoints.d.ts:3753:    initial_data_source?: InitialDataSourceRequest;
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3754-    icon?: PageIconRequest;
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3755-    cover?: PageCoverRequest;
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3756-};
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3757-export type CreateDatabaseParameters = CreateDatabaseBodyParameters;
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3758-export type CreateDatabaseResponse = PartialDatabaseObjectResponse | DatabaseObjectResponse;
--
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3761- */
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3762-export declare const createDatabase: {
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3763-    readonly method: "post";
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3764-    readonly pathParams: readonly [];
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3765-    readonly queryParams: readonly [];
node_modules/@notionhq/client/build/src/api-endpoints.d.ts:3766:    readonly bodyParams: readonly ["parent", "title", "description", "is_inline", "initial_data_source", "icon", "cover"];
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3767-    readonly path: () => string;
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3768-};
~/dev/audits/notion-universal-baseline-2026-03-13-opus/node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3769-type SearchBodyParameters = {
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3770-    sort?: {
node_modules/@notionhq/client/build/src/api-endpoints.d.ts-3771-        timestamp: "last_edited_time";
--
node_modules/@notionhq/client/build/src/api-endpoints.js.map:1:[Omitted long matching line]

1383-    archived: boolean;
1384-};
1385:type InitialDataSourceRequest = {
1386-    properties?: Record<string, PropertyConfigurationRequest>;
1387-};
--
3751-    description?: Array<RichTextItemRequest>;
3752-    is_inline?: boolean;
3753:    initial_data_source?: InitialDataSourceRequest;
3754-    icon?: PageIconRequest;
3755-    cover?: PageCoverRequest;

1864-    in_trash: boolean;
1865-    /** @deprecated Use `in_trash` instead. Present for backwards compatibility with API versions prior to 2026-03-11. */
1866-    archived: boolean;
1867-};
1868-type PeopleArrayBasedPropertyValueResponse = {
1869-    type: "people";
1870-    people: Array<UserValueResponse | GroupObjectResponse>;
1871-};
1872-type PeopleDatabasePropertyConfigResponse = {
1873-    type: "people";
1874-    people: EmptyObject;
1875-};
1876-type PeoplePropertyConfigurationRequest = {
1877-    type?: "people";
1878-    people: EmptyObject;
1879-};
1880-type PeoplePropertyFilter = {
1881-    contains: IdRequest;
1882-} | {
1883-    does_not_contain: IdRequest;
1884-} | ExistencePropertyFilter;
1885-export type PeoplePropertyItemObjectResponse = {
1886-    type: "people";
1887-    people: PartialUserObjectResponse | UserObjectResponse;
1888-    object: "property_item";
1889-    id: string;
1890-};
1891-export type PersonUserObjectResponse = {
1892-    type: "person";
1893-    person: {
1894-        email?: string;
1895-    };
1896-};
1897-type PhoneNumberDatabasePropertyConfigResponse = {
1898-    type: "phone_number";
1899-    phone_number: EmptyObject;
1900-};
1901-type PhoneNumberPropertyConfigurationRequest = {
1902-    type?: "phone_number";
1903-    phone_number: EmptyObject;
1904-};
1905-export type PhoneNumberPropertyItemObjectResponse = {
1906-    type: "phone_number";
1907-    phone_number: string | null;
1908-    object: "property_item";
1909-    id: string;
1910-};
1911-type PhoneNumberSimplePropertyValueResponse = {
1912-    type: "phone_number";
1913-    phone_number: string | null;
1914-};
1915-type PlacePropertyConfigurationRequest = {
1916-    type?: "place";
1917-    place: EmptyObject;
1918-};
1919-export type PlacePropertyItemObjectResponse = {
1920-    type: "place";
1921-    place: {
1922-        lat: number;
1923-        lon: number;
1924-        name?: string | null;
1925-        address?: string | null;
1926-        aws_place_id?: string | null;
1927-        google_place_id?: string | null;
1928-    } | null;
1929-    object: "property_item";
1930-    id: string;
1931-};
1932-type PlacePropertyValueResponse = {
1933-    lat: number;
1934-    lon: number;
1935-    name?: string | null;
1936-    address?: string | null;
1937-    aws_place_id?: string | null;
1938-    google_place_id?: string | null;
1939-};
1940-type PlaceSimplePropertyValueResponse = {
1941-    type: "place";
1942-    place: PlacePropertyValueResponse | null;
1943-};
1944:[Omitted long matching line]
1945:type PropertyConfigurationRequestCommon = {
1946-    description?: PropertyDescriptionRequest | null;
1947-};
1948-type PropertyDescriptionRequest = string;
1949-type PropertyFilter = {
1950-    title: TextPropertyFilter;
1951-    property: string;
1952-    type?: "title";
1953-} | {
1954-    rich_text: TextPropertyFilter;
1955-    property: string;
1956-    type?: "rich_text";
1957-} | {
1958-    number: NumberPropertyFilter;
1959-    property: string;
1960-    type?: "number";
1961-} | {
1962-    checkbox: CheckboxPropertyFilter;
1963-    property: string;
1964-    type?: "checkbox";
1965-} | {
1966-    select: SelectPropertyFilter;
1967-    property: string;
1968-    type?: "select";
1969-} | {
1970-    multi_select: MultiSelectPropertyFilter;
1971-    property: string;
1972-    type?: "multi_select";
1973-} | {
1974-    status: StatusPropertyFilter;
1975-    property: string;
1976-    type?: "status";
1977-} | {
1978-    date: DatePropertyFilter;
1979-    property: string;
1980-    type?: "date";
1981-} | {
1982-    people: PeoplePropertyFilter;
1983-    property: string;
1984-    type?: "people";
1985-} | {
1986-    files: ExistencePropertyFilter;
1987-    property: string;
1988-    type?: "files";
1989-} | {
1990-    url: TextPropertyFilter;
1991-    property: string;
1992-    type?: "url";
1993-} | {
1994-    email: TextPropertyFilter;
1995-    property: string;
1996-    type?: "email";
1997-} | {
1998-    phone_number: TextPropertyFilter;
1999-    property: string;
2000-    type?: "phone_number";
2001-} | {
2002-    relation: RelationPropertyFilter;
2003-    property: string;
2004-    type?: "relation";
2005-} | {
2006-    created_by: PeoplePropertyFilter;
2007-    property: string;
2008-    type?: "created_by";
2009-} | {
2010-    created_time: DatePropertyFilter;
2011-    property: string;
2012-    type?: "created_time";
2013-} | {
2014-    last_edited_by: PeoplePropertyFilter;
2015-    property: string;
2016-    type?: "last_edited_by";
2017-} | {
2018-    last_edited_time: DatePropertyFilter;
2019-    property: string;
2020-    type?: "last_edited_time";
2021-} | {
2022-    formula: FormulaPropertyFilter;
2023-    property: string;
2024-    type?: "formula";
2025-} | {

  1944→type PropertyConfigurationRequest = PropertyConfigurationRequestCommon & (NumberPropertyConfigurationRequest | FormulaPropertyConfigurationRequest | SelectPropertyConfigurationRequest | MultiSelectPropertyConfigurationRequest | StatusPropertyConfigurationRequest | RelationPropertyConfigurationRequest | RollupPropertyConfigurationRequest | UniqueIdPropertyConfigurationRequest | TitlePropertyConfigurationRequest | RichTextPropertyConfigurationRequest | UrlPropertyConfigurationRequest | PeoplePropertyConfigurationRequest | FilesPropertyConfigurationRequest | EmailPropertyConfigurationRequest | PhoneNumberPropertyConfigurationRequest | DatePropertyConfigurationRequest | CheckboxPropertyConfigurationRequest | CreatedByPropertyConfigurationRequest | CreatedTimePropertyConfigurationRequest | LastEditedByPropertyConfigurationRequest | LastEditedTimePropertyConfigurationRequest | ButtonPropertyConfigurationRequest | LocationPropertyConfigurationRequest | VerificationPropertyConfigurationRequest | LastVisitedTimePropertyConfigurationRequest | PlacePropertyConfigurationRequest);
  1945→type PropertyConfigurationRequestCommon = {

929-    type: "date";
930-    date: EmptyObject;
931-};
932-type DateFormulaPropertyResponse = {
933-    type: "date";
934-    date: DateResponse | null;
935-};
936-type DateFormulaPropertyValueResponse = {
937-    type: "date";
938-    date: DateResponse | null;
939-};
940-type DatePartialRollupValueResponse = {
941-    type: "date";
942-    date: DateResponse | null;
943-};
944:type DatePropertyConfigurationRequest = {
945-    type?: "date";
946-    date: EmptyObject;
947-};
948-type DatePropertyFilter = {
949-    equals: string;
950-} | {
951-    before: string;
952-} | {
953-    after: string;
954-} | {
955-    on_or_before: string;
956-} | {
957-    on_or_after: string;
958-} | {
959-    this_week: EmptyObject;
--
1672-    };
1673-};
1674-type NumberFormat = string;
1675-type NumberFormulaPropertyResponse = {
1676-    type: "number";
1677-    number: number | null;
1678-};
1679-type NumberFormulaPropertyValueResponse = {
1680-    type: "number";
1681-    number: number | null;
1682-};
1683-type NumberPartialRollupValueResponse = {
1684-    type: "number";
1685-    number: number | null;
1686-};
1687:type NumberPropertyConfigurationRequest = {
1688-    type?: "number";
1689-    number: {
1690-        format?: NumberFormat;
1691-    };
1692-};
1693-type NumberPropertyFilter = {
1694-    equals: number;
1695-} | {
1696-    does_not_equal: number;
1697-} | {
1698-    greater_than: number;
1699-} | {
1700-    less_than: number;
1701-} | {
1702-    greater_than_or_equal_to: number;
--
2260-    files: ExistencePropertyFilter;
2261-} | {
2262-    status: StatusPropertyFilter;
2263-};
2264-/**
2265- * One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`,
2266- * `pink`, `red`
2267- */
2268-type SelectColor = "default" | "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red";
2269-type SelectDatabasePropertyConfigResponse = {
2270-    type: "select";
2271-    select: {
2272-        options: Array<SelectPropertyResponse>;
2273-    };
2274-};
2275:type SelectPropertyConfigurationRequest = {
2276-    type?: "select";
2277-    select: {
2278-        options?: Array<{
2279-            name: string;
2280-            color?: SelectColor;
2281-            description?: string | null;
2282-        }>;
2283-    };
2284-};
2285-type SelectPropertyFilter = {
2286-    equals: string;
2287-} | {
2288-    does_not_equal: string;
2289-} | ExistencePropertyFilter;
2290-export type SelectPropertyItemObjectResponse = {

2761-};
2762-export type ListUsersParameters = ListUsersQueryParameters;
2763-export type ListUsersResponse = {
2764-    type: "user";
2765-    user: EmptyObject;
2766-    object: "list";
2767-    next_cursor: string | null;
2768-    has_more: boolean;
2769-    results: Array<UserObjectResponse>;
2770-};
2771-/**
2772- * List all users
2773- */
2774-export declare const listUsers: {
2775-    readonly method: "get";
2776-    readonly pathParams: readonly [];
2777-    readonly queryParams: readonly ["start_cursor", "page_size"];
2778-    readonly bodyParams: readonly [];
2779-    readonly path: () => string;
2780-};
2781:type CreatePageBodyParameters = {
2782-    parent?: {
2783-        page_id: IdRequest;
2784-        type?: "page_id";
2785-    } | {
2786-        database_id: IdRequest;
2787-        type?: "database_id";
2788-    } | {
2789-        data_source_id: IdRequest;
2790-        type?: "data_source_id";
2791-    } | {
2792-        workspace: true;
2793-        type?: "workspace";
2794-    };
2795-    properties?: Record<string, {
2796-        title: Array<RichTextItemRequest>;
2797-        type?: "title";
2798-    } | {
2799-        rich_text: Array<RichTextItemRequest>;
2800-        type?: "rich_text";
2801-    } | {
--
2875-        } | null;
2876-        type?: "place";
2877-    }>;
2878-    icon?: PageIconRequest | null;
2879-    cover?: PageCoverRequest | null;
2880-    content?: Array<BlockObjectRequest>;
2881-    children?: Array<BlockObjectRequest>;
2882-    markdown?: string;
2883-    template?: {
2884-        type: "none";
2885-    } | {
2886-        type: "default";
2887-        timezone?: TemplateTimezone;
2888-    } | {
2889-        type: "template_id";
2890-        template_id: IdRequest;
2891-        timezone?: TemplateTimezone;
2892-    };
2893-    position?: PagePositionSchema;
2894-};
2895:export type CreatePageParameters = CreatePageBodyParameters;
2896-export type CreatePageResponse = PageObjectResponse | PartialPageObjectResponse;
2897-/**
2898- * Create a page
2899- */
2900-export declare const createPage: {
2901-    readonly method: "post";
2902-    readonly pathParams: readonly [];
2903-    readonly queryParams: readonly [];
2904-    readonly bodyParams: readonly ["parent", "properties", "icon", "cover", "content", "children", "markdown", "template", "position"];
2905-    readonly path: () => string;
2906-};
2907-type GetPagePathParameters = {
2908-    page_id: IdRequest;
2909-};
2910-type GetPageQueryParameters = {
2911-    filter_properties?: Array<string>;
2912-};
2913-export type GetPageParameters = GetPagePathParameters & GetPageQueryParameters;
2914-export type GetPageResponse = PartialPageObjectResponse | PageObjectResponse;
2915-/**

883-    public_url: string | null;
884-};
885-type DataSourceParentResponse = {
886:    type: "data_source_id";
887:    data_source_id: IdResponse;
888-    database_id: IdResponse;
889-};
890-type DataSourceReferenceResponse = {
--
923-type DatabasePropertyRelationConfigResponse = DatabasePropertyRelationConfigResponseCommon & (SinglePropertyDatabasePropertyRelationConfigResponse | DualPropertyDatabasePropertyRelationConfigResponse);
924-type DatabasePropertyRelationConfigResponseCommon = {
925-    database_id: IdResponse;
926:    data_source_id: IdResponse;
927-};
928-type DateDatabasePropertyConfigResponse = {
929-    type: "date";
--
1799-};
1800-/**
1801- * The parent of the data source. This is typically a database (`database_id`), but for
1802: * externally synced data sources, can be another data source (`data_source_id`).
1803- */
1804-type ParentOfDataSourceResponse = DatabaseParentResponse | DataSourceParentResponse;
1805-type ParentOfDatabaseResponse = PageIdParentForBlockBasedObjectResponse | WorkspaceParentForBlockBasedObjectResponse | DatabaseParentResponse | BlockIdParentForBlockBasedObjectResponse;
--
2121-type RelationPropertyConfigurationRequest = {
2122-    type?: "relation";
2123-    relation: {
2124:        data_source_id: IdRequest;
2125-    } & ({
2126-        type?: "single_property";
2127-        single_property: EmptyObject;
--
2786-        database_id: IdRequest;
2787-        type?: "database_id";
2788-    } | {
2789:        data_source_id: IdRequest;
2790:        type?: "data_source_id";
2791-    } | {
2792-        workspace: true;

[Showing results with pagination = limit: 40, offset: 0]

     1→import type { Agent } from "node:http";
     2→import { type Logger, LogLevel } from "./logging";
     3→import { type GetBlockParameters, type GetBlockResponse, type UpdateBlockParameters, type UpdateBlockResponse, type DeleteBlockParameters, type DeleteBlockResponse, type AppendBlockChildrenParameters, type AppendBlockChildrenResponse, type ListBlockChildrenParameters, type ListBlockChildrenResponse, type QueryDataSourceParameters, type QueryDataSourceResponse, type CreateDataSourceParameters, type CreateDataSourceResponse, type UpdateDataSourceParameters, type UpdateDataSourceResponse, type GetDataSourceParameters, type GetDataSourceResponse, type CreatePageParameters, type CreatePageResponse, type GetPageParameters, type GetPageResponse, type UpdatePageParameters, type UpdatePageResponse, type MovePageParameters, type MovePageResponse, type GetPageMarkdownParameters, type GetPageMarkdownResponse, type UpdatePageMarkdownParameters, type UpdatePageMarkdownResponse, type GetUserParameters, type GetUserResponse, type ListUsersParameters, type ListUsersResponse, type SearchParameters, type SearchResponse, type GetSelfParameters, type GetSelfResponse, type GetPagePropertyParameters, type GetPagePropertyResponse, type CreateCommentParameters, type CreateCommentResponse, type ListCommentsParameters, type ListCommentsResponse, type GetCommentParameters, type GetCommentResponse, type OauthTokenResponse, type OauthTokenParameters, type OauthIntrospectResponse, type OauthIntrospectParameters, type OauthRevokeResponse, type OauthRevokeParameters, type CreateFileUploadParameters, type CreateFileUploadResponse, type GetFileUploadResponse, type GetFileUploadParameters, type SendFileUploadParameters, type SendFileUploadResponse, type CompleteFileUploadParameters, type CompleteFileUploadResponse, type ListFileUploadsParameters, type ListFileUploadsResponse, GetDatabaseParameters, GetDatabaseResponse, CreateDatabaseResponse, CreateDatabaseParameters, UpdateDatabaseParameters, UpdateDatabaseResponse, ListDataSourceTemplatesResponse, ListDataSourceTemplatesParameters } from "./api-endpoints";
     4→import type { SupportedFetch } from "./fetch-types";
     5→export type RetryOptions = {
     6→    /**
     7→     * Maximum number of retry attempts. Set to 0 to disable retries.
     8→     * @default 2
     9→     */
    10→    maxRetries?: number;
    11→    /**
    12→     * Initial delay between retries in milliseconds.
    13→     * Used as base for exponential back-off when retry-after header is absent.
    14→     * @default 1000
    15→     */
    16→    initialRetryDelayMs?: number;
    17→    /**
    18→     * Maximum delay between retries in milliseconds.
    19→     * @default 60000
    20→     */
    21→    maxRetryDelayMs?: number;
    22→};
    23→export type ClientOptions = {
    24→    auth?: string;
    25→    timeoutMs?: number;
    26→    baseUrl?: string;
    27→    logLevel?: LogLevel;
    28→    logger?: Logger;
    29→    notionVersion?: string;
    30→    fetch?: SupportedFetch;
    31→    /** Silently ignored in the browser */
    32→    agent?: Agent;
    33→    /**
    34→     * Configuration for automatic retries on rate limit (429) and server errors.
    35→     * Set to false to disable retries entirely.
    36→     */
    37→    retry?: RetryOptions | false;
    38→};
    39→type FileParam = {
    40→    filename?: string;
    41→    data: string | Blob;
    42→};
    43→export type RequestParameters = {
    44→    path: string;
    45→    method: Method;
    46→    query?: QueryParams;
    47→    body?: Record<string, unknown>;
    48→    formDataParams?: Record<string, string | FileParam>;
    49→    headers?: Record<string, string>;
    50→    /**
    51→     * To authenticate using public API token, `auth` should be passed as a
    52→     * string. If you are trying to complete OAuth, then `auth` should be an object
    53→     * containing your integration's client ID and secret.
    54→     */
    55→    auth?: string | {
    56→        client_id: string;
    57→        client_secret: string;
    58→    };
    59→};
    60→export default class Client {
    61→    #private;
    62→    static readonly defaultNotionVersion = "2025-09-03";
    63→    constructor(options?: ClientOptions);
    64→    /**
    65→     * Sends a request.
    66→     */
    67→    request<ResponseBody extends object>(args: RequestParameters): Promise<ResponseBody>;
    68→    /**
    69→     * Builds the full URL with query parameters.
    70→     */
    71→    private buildRequestUrl;
    72→    /**
    73→     * Serializes the request body to JSON string if non-empty.
    74→     */
    75→    private serializeBody;
    76→    /**
    77→     * Builds the request headers including auth and content-type.
    78→     */
    79→    private buildRequestHeaders;
    80→    /**
    81→     * Builds the authorization header based on auth type.
    82→     */
    83→    private buildAuthHeader;
    84→    /**
    85→     * Builds FormData from form parameters if provided.
    86→     * Also removes content-type header to let fetch set the boundary.
    87→     */
    88→    private buildFormData;
    89→    /**
    90→     * Executes the request with retry logic.
    91→     */
    92→    private executeWithRetry;
    93→    /**
    94→     * Executes a single HTTP request (no retry).
    95→     */
    96→    private executeSingleRequest;
    97→    /**
    98→     * Logs a request error with appropriate detail level.
    99→     */
   100→    private logRequestError;
   101→    /**
   102→     * Extracts request_id from an object if present.
   103→     */
   104→    private extractRequestId;
   105→    /**
   106→     * Determines if an error can be retried based on its error code and method.
   107→     * Rate limits (429) are always retryable since the server explicitly asks us
   108→     * to retry. Server errors (500, 503) are only retried for idempotent methods
   109→     * (GET, DELETE) to avoid duplicate side effects.
   110→     */
   111→    private canRetry;
   112→    /**
   113→     * Calculates the delay before the next retry attempt.
   114→     * Uses retry-after header if present, otherwise exponential back-off with
   115→     * jitter.
   116→     */
   117→    private calculateRetryDelay;
   118→    /**
   119→     * Parses the retry-after header value.
   120→     * Supports both delta-seconds (e.g., "120") and HTTP-date formats.
   121→     * Returns the delay in milliseconds, or undefined if not present or invalid.
   122→     */
   123→    private parseRetryAfterHeader;
   124→    private sleep;
   125→    readonly blocks: {
   126→        /**
   127→         * Retrieve block
   128→         */
   129→        retrieve: (args: WithAuth<GetBlockParameters>) => Promise<GetBlockResponse>;
   130→        /**
   131→         * Update block
   132→         */
   133→        update: (args: WithAuth<UpdateBlockParameters>) => Promise<UpdateBlockResponse>;
   134→        /**
   135→         * Delete block
   136→         */
   137→        delete: (args: WithAuth<DeleteBlockParameters>) => Promise<DeleteBlockResponse>;
   138→        children: {
   139→            /**
   140→             * Append block children
   141→             */
   142→            append: (args: WithAuth<AppendBlockChildrenParameters>) => Promise<AppendBlockChildrenResponse>;
   143→            /**
   144→             * Retrieve block children
   145→             */
   146→            list: (args: WithAuth<ListBlockChildrenParameters>) => Promise<ListBlockChildrenResponse>;
   147→        };
   148→    };
   149→    readonly databases: {
   150→        /**
   151→         * Retrieve a database
   152→         */
   153→        retrieve: (args: WithAuth<GetDatabaseParameters>) => Promise<GetDatabaseResponse>;
   154→        /**
   155→         * Create a database
   156→         */
   157→        create: (args: WithAuth<CreateDatabaseParameters>) => Promise<CreateDatabaseResponse>;
   158→        /**
   159→         * Update a database
   160→         */
   161→        update: (args: WithAuth<UpdateDatabaseParameters>) => Promise<UpdateDatabaseResponse>;
   162→    };
   163→    readonly dataSources: {
   164→        /**
   165→         * Retrieve a data source
   166→         */
   167→        retrieve: (args: WithAuth<GetDataSourceParameters>) => Promise<GetDataSourceResponse>;
   168→        /**
   169→         * Query a data source
   170→         */
   171→        query: (args: WithAuth<QueryDataSourceParameters>) => Promise<QueryDataSourceResponse>;
   172→        /**
   173→         * Create a data source
   174→         */
   175→        create: (args: WithAuth<CreateDataSourceParameters>) => Promise<CreateDataSourceResponse>;
   176→        /**
   177→         * Update a data source
   178→         */
   179→        update: (args: WithAuth<UpdateDataSourceParameters>) => Promise<UpdateDataSourceResponse>;
   180→        /**
   181→         * List page templates that are available for a data source
   182→         */
   183→        listTemplates: (args: WithAuth<ListDataSourceTemplatesParameters>) => Promise<ListDataSourceTemplatesResponse>;
   184→    };
   185→    readonly pages: {
   186→        /**
   187→         * Create a page
   188→         */
   189→        create: (args: WithAuth<CreatePageParameters>) => Promise<CreatePageResponse>;
   190→        /**
   191→         * Retrieve a page
   192→         */
   193→        retrieve: (args: WithAuth<GetPageParameters>) => Promise<GetPageResponse>;
   194→        /**
   195→         * Update page properties
   196→         */
   197→        update: (args: WithAuth<UpdatePageParameters>) => Promise<UpdatePageResponse>;
   198→        /**
   199→         * Move a page
   200→         */
   201→        move: (args: WithAuth<MovePageParameters>) => Promise<MovePageResponse>;
   202→        /**
   203→         * Retrieve a page as markdown
   204→         */
   205→        retrieveMarkdown: (args: WithAuth<GetPageMarkdownParameters>) => Promise<GetPageMarkdownResponse>;
   206→        /**
   207→         * Update a page's content as markdown
   208→         */
   209→        updateMarkdown: (args: WithAuth<UpdatePageMarkdownParameters>) => Promise<UpdatePageMarkdownResponse>;
   210→        properties: {
   211→            /**
   212→             * Retrieve page property
   213→             */
   214→            retrieve: (args: WithAuth<GetPagePropertyParameters>) => Promise<GetPagePropertyResponse>;
   215→        };
   216→    };
   217→    readonly users: {
   218→        /**
   219→         * Retrieve a user
   220→         */
   221→        retrieve: (args: WithAuth<GetUserParameters>) => Promise<GetUserResponse>;
   222→        /**
   223→         * List all users
   224→         */
   225→        list: (args: WithAuth<ListUsersParameters>) => Promise<ListUsersResponse>;
   226→        /**
   227→         * Get details about bot
   228→         */
   229→        me: (args: WithAuth<GetSelfParameters>) => Promise<GetSelfResponse>;
   230→    };
   231→    readonly comments: {
   232→        /**
   233→         * Create a comment
   234→         */
   235→        create: (args: WithAuth<CreateCommentParameters>) => Promise<CreateCommentResponse>;
   236→        /**
   237→         * List comments
   238→         */
   239→        list: (args: WithAuth<ListCommentsParameters>) => Promise<ListCommentsResponse>;
   240→        /**
   241→         * Retrieve a comment
   242→         */
   243→        retrieve: (args: WithAuth<GetCommentParameters>) => Promise<GetCommentResponse>;
   244→    };
   245→    readonly fileUploads: {
   246→        /**
   247→         * Create a file upload
   248→         */
   249→        create: (args: WithAuth<CreateFileUploadParameters>) => Promise<CreateFileUploadResponse>;
   250→        /**
   251→         * Retrieve a file upload
   252→         */
   253→        retrieve: (args: WithAuth<GetFileUploadParameters>) => Promise<GetFileUploadResponse>;
   254→        /**
   255→         * List file uploads
   256→         */
   257→        list: (args: WithAuth<ListFileUploadsParameters>) => Promise<ListFileUploadsResponse>;
   258→        /**
   259→         * Send a file upload
   260→         *
   261→         * Requires a `file_upload_id`, obtained from the `id` of the Create File
   262→         * Upload API response.
   263→         *
   264→         * The `file` parameter contains the raw file contents or Blob/File object
   265→         * under `file.data`, and an optional `file.filename` string.
   266→         *
   267→         * Supply a stringified `part_number` parameter when using file uploads
   268→         * in multi-part mode.
   269→         *
   270→         * This endpoint sends HTTP multipart/form-data instead of JSON parameters.
   271→         */
   272→        send: (args: WithAuth<SendFileUploadParameters>) => Promise<SendFileUploadResponse>;
   273→        /**
   274→         * Complete a file upload
   275→         */
   276→        complete: (args: WithAuth<CompleteFileUploadParameters>) => Promise<CompleteFileUploadResponse>;
   277→    };
   278→    /**
   279→     * Search
   280→     */
   281→    search: (args: WithAuth<SearchParameters>) => Promise<SearchResponse>;
   282→    readonly oauth: {
   283→        /**
   284→         * Get token
   285→         */
   286→        token: (args: OauthTokenParameters & {
   287→            client_id: string;
   288→            client_secret: string;
   289→        }) => Promise<OauthTokenResponse>;
   290→        /**
   291→         * Introspect token
   292→         */
   293→        introspect: (args: OauthIntrospectParameters & {
   294→            client_id: string;
   295→            client_secret: string;
   296→        }) => Promise<OauthIntrospectResponse>;
   297→        /**
   298→         * Revoke token
   299→         */
   300→        revoke: (args: OauthRevokeParameters & {
   301→            client_id: string;
   302→            client_secret: string;
   303→        }) => Promise<OauthRevokeResponse>;
   304→    };
   305→    /**
   306→     * Logs a warning when the caller passes parameters that are not recognized
   307→     * by the endpoint definition. This helps catch typos and renamed parameters
   308→     * (e.g. `archived` vs `in_trash` for `databases.update`) that would
   309→     * otherwise be silently dropped by `pick()`.
   310→     */
   311→    private warnUnknownParams;
   312→    /**
   313→     * Emits a log message to the console.
   314→     *
   315→     * @param level The level for this message
   316→     * @param args Arguments to send to the console
   317→     */
   318→    private log;
   319→    /**
   320→     * Transforms an API key or access token into a headers object suitable for an HTTP request.
   321→     *
   322→     * This method uses the instance's value as the default when the input is undefined. If neither are defined, it returns
   323→     * an empty object
   324→     *
   325→     * @param auth API key or access token
   326→     * @returns headers key-value object
   327→     */
   328→    private authAsHeaders;
   329→}
   330→type Method = "get" | "post" | "patch" | "delete";
   331→type QueryParams = Record<string, string | number | boolean | string[]> | URLSearchParams;
   332→type WithAuth<P> = P & {
   333→    auth?: string;
   334→};
   335→export {};
   336→//# sourceMappingURL=Client.d.ts.map

3585-    parent?: ParentOfDataSourceRequest;
3586-};
3587-export type UpdateDataSourceParameters = UpdateDataSourcePathParameters & UpdateDataSourceBodyParameters;
3588-export type UpdateDataSourceResponse = PartialDataSourceObjectResponse | DataSourceObjectResponse;
3589-/**
3590- * Update a data source
3591- */
3592-export declare const updateDataSource: {
3593-    readonly method: "patch";
3594-    readonly pathParams: readonly ["data_source_id"];
3595-    readonly queryParams: readonly [];
3596-    readonly bodyParams: readonly ["archived", "title", "icon", "properties", "in_trash", "parent"];
3597-    readonly path: (p: UpdateDataSourcePathParameters) => string;
3598-};
3599-type QueryDataSourcePathParameters = {
3600-    data_source_id: IdRequest;
3601-};
3602-type QueryDataSourceQueryParameters = {
3603-    filter_properties?: Array<string>;
3604-};
3605:type QueryDataSourceBodyParameters = {
3606-    sorts?: Array<{
3607-        property: string;
3608-        direction: "ascending" | "descending";
3609-    } | {
3610-        timestamp: "created_time" | "last_edited_time";
3611-        direction: "ascending" | "descending";
3612-    }>;
3613-    filter?: {
3614-        or: GroupFilterOperatorArray;
3615-    } | {
3616-        and: GroupFilterOperatorArray;
3617-    } | PropertyFilter | TimestampFilter;
3618-    start_cursor?: string;
3619-    page_size?: number;
3620-    in_trash?: boolean;
3621-    /** @deprecated Use `in_trash` instead. */
3622-    archived?: boolean;
3623-    result_type?: "page" | "data_source";
3624-};
3625:export type QueryDataSourceParameters = QueryDataSourcePathParameters & QueryDataSourceQueryParameters & QueryDataSourceBodyParameters;
3626:export type QueryDataSourceResponse = {
3627-    type: "page_or_data_source";
3628-    page_or_data_source: EmptyObject;
3629-    object: "list";
3630-    next_cursor: string | null;
3631-    has_more: boolean;
3632-    results: Array<PageObjectResponse | PartialPageObjectResponse | PartialDataSourceObjectResponse | DataSourceObjectResponse>;
3633-};
3634-/**
3635- * Query a data source
3636- */
3637-export declare const queryDataSource: {
3638-    readonly method: "post";
3639-    readonly pathParams: readonly ["data_source_id"];
3640-    readonly queryParams: readonly ["filter_properties"];
3641-    readonly bodyParams: readonly ["archived", "sorts", "filter", "start_cursor", "page_size", "in_trash", "result_type"];
3642-    readonly path: (p: QueryDataSourcePathParameters) => string;
3643-};
3644-type CreateDataSourceBodyParameters = {
3645-    parent: ParentOfDataSourceRequest;
3646-    properties: Record<string, PropertyConfigurationRequest>;

859-type CustomEmojiResponse = {
860-    id: IdResponse;
861-    name: string;
862-    url: string;
863-};
864:export type DataSourceObjectResponse = {
865-    object: "data_source";
866-    id: IdResponse;
867-    title: Array<RichTextItemResponse>;
868-    description: Array<RichTextItemResponse>;
869-    parent: ParentOfDataSourceResponse;
--
1809-};
1810-export type PartialCommentObjectResponse = {
1811-    object: "comment";
1812-    id: IdResponse;
1813-};
1814:export type PartialDataSourceObjectResponse = {
1815-    object: "data_source";
1816-    id: IdResponse;
1817-    properties: Record<string, DatabasePropertyConfigResponse>;
1818-};
1819-export type PartialDatabaseObjectResponse = {
--
3435-};
3436-type GetDataSourcePathParameters = {
3437-    data_source_id: IdRequest;
3438-};
3439-export type GetDataSourceParameters = GetDataSourcePathParameters;
3440:export type GetDataSourceResponse = PartialDataSourceObjectResponse | DataSourceObjectResponse;

[Showing results with pagination = limit: 30, offset: 0]

   864→export type DataSourceObjectResponse = {
   865→    object: "data_source";
   866→    id: IdResponse;
   867→    title: Array<RichTextItemResponse>;
   868→    description: Array<RichTextItemResponse>;
   869→    parent: ParentOfDataSourceResponse;
   870→    database_parent: ParentOfDatabaseResponse;
   871→    is_inline: boolean;
   872→    in_trash: boolean;
   873→    /** @deprecated Use `in_trash` instead. Present for backwards compatibility with API versions prior to 2026-03-11. */
   874→    archived: boolean;
   875→    created_time: string;
   876→    last_edited_time: string;
   877→    created_by: PartialUserObjectResponse;
   878→    last_edited_by: PartialUserObjectResponse;
   879→    properties: Record<string, DatabasePropertyConfigResponse>;
   880→    icon: PageIconResponse | null;
   881→    cover: PageCoverResponse | null;
   882→    url: string;
   883→    public_url: string | null;
   884→};
   885→type DataSourceParentResponse = {
   886→    type: "data_source_id";
   887→    data_source_id: IdResponse;
   888→    database_id: IdResponse;
   889→};
   890→type DataSourceReferenceResponse = {
   891→    id: IdResponse;
   892→    name: string;
   893→};

884-};
885-type DataSourceParentResponse = {
886-    type: "data_source_id";
887-    data_source_id: IdResponse;
888-    database_id: IdResponse;
889-};
890-type DataSourceReferenceResponse = {
891-    id: IdResponse;
892-    name: string;
893-};
894:export type DatabaseObjectResponse = {
895-    object: "database";
896-    id: IdResponse;
897-    title: Array<RichTextItemResponse>;
898-    description: Array<RichTextItemResponse>;
899-    parent: ParentOfDatabaseResponse;
900-    is_inline: boolean;
901-    in_trash: boolean;
902-    /** @deprecated Use `in_trash` instead. Present for backwards compatibility with API versions prior to 2026-03-11. */
903-    archived: boolean;
904-    is_locked: boolean;
--
1809-};
1810-export type PartialCommentObjectResponse = {
1811-    object: "comment";
1812-    id: IdResponse;
1813-};
1814-export type PartialDataSourceObjectResponse = {
1815-    object: "data_source";
1816-    id: IdResponse;

[Showing results with pagination = limit: 30, offset: 0]

   894→export type DatabaseObjectResponse = {
   895→    object: "database";
   896→    id: IdResponse;
   897→    title: Array<RichTextItemResponse>;
   898→    description: Array<RichTextItemResponse>;
   899→    parent: ParentOfDatabaseResponse;
   900→    is_inline: boolean;
   901→    in_trash: boolean;
   902→    /** @deprecated Use `in_trash` instead. Present for backwards compatibility with API versions prior to 2026-03-11. */
   903→    archived: boolean;
   904→    is_locked: boolean;
   905→    created_time: string;
   906→    last_edited_time: string;
   907→    data_sources: Array<DataSourceReferenceResponse>;
   908→    icon: PageIconResponse | null;
   909→    cover: PageCoverResponse | null;
   910→    url: string;
   911→    public_url: string | null;
   912→};
   913→type DatabaseParentResponse = {
   914→    type: "database_id";
   915→    database_id: IdResponse;
   916→};
   917→type DatabasePropertyConfigResponse = DatabasePropertyConfigResponseCommon & (NumberDatabasePropertyConfigResponse | FormulaDatabasePropertyConfigResponse | SelectDatabasePropertyConfigResponse | MultiSelectDatabasePropertyConfigResponse | StatusDatabasePropertyConfigResponse | RelationDatabasePropertyConfigResponse | RollupDatabasePropertyConfigResponse | UniqueIdDatabasePropertyConfigResponse | TitleDatabasePropertyConfigResponse | RichTextDatabasePropertyConfigResponse | UrlDatabasePropertyConfigResponse | PeopleDatabasePropertyConfigResponse | FilesDatabasePropertyConfigResponse | EmailDatabasePropertyConfigResponse | PhoneNumberDatabasePropertyConfigResponse | DateDatabasePropertyConfigResponse | CheckboxDatabasePropertyConfigResponse | CreatedByDatabasePropertyConfigResponse | CreatedTimeDatabasePropertyConfigResponse | LastEditedByDatabasePropertyConfigResponse | LastEditedTimeDatabasePropertyConfigResponse);
   918→type DatabasePropertyConfigResponseCommon = {
   919→    id: string;
   920→    name: string;
   921→    description: PropertyDescriptionRequest | null;
   922→};
   923→type DatabasePropertyRelationConfigResponse = DatabasePropertyRelationConfigResponseCommon & (SinglePropertyDatabasePropertyRelationConfigResponse | DualPropertyDatabasePropertyRelationConfigResponse);

# Database Query Documentation Summary

## Deprecation Notice

This endpoint has been **deprecated as of version 2025-09-03**. The documentation explicitly states: *"This page describes the API for versions up to and including `2022-06-28`."* Users should migrate to the newer [Query a data source](/reference/query-a-data-source) API instead.

## What the Page Covers

The deprecated endpoint retrieves pages and/or databases from a database, with filtering and sorting capabilities. Key features include:

**Filtering**: *"Filters operate on database properties and can be combined. If no filter is provided, all the pages in the database will be returned with pagination."* Filters support compound logic with "and"/"or" operators.

**Sorting**: *"Sorts operate on database properties or page timestamps and can be combined."*

**Property Filtering**: Results can be narrowed using the `filter_properties` query parameter to specify which properties return.

## Requirements & Permissions

- The database must be shared with the integration
- Integration requires "read content capabilities"
- Failed access returns HTTP 404 or 403 status codes

## Known Limitations

Formula and rollup properties have constraints: *"If a formula depends on a page property that is a relation, and that relation has more than 25 references, only 25 will be evaluated."*

The page provides no specific endpoint URL, parameter details, or request/response examples—it references separate documentation pages for those specifics.

# Notion Data Source Query API Reference

## Endpoint

**Method:** `POST`  
**URL:** `https://api.notion.com/v1/data_sources/{data_source_id}/query`

## Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string (UUID) | Yes | The identifier for the data source to query |

## Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `filter_properties[]` | array of strings | Restrict returned properties by name or ID (improves performance) |

## Request Body

```json
{
  "filter": { /* filter object */ },
  "sorts": [ /* sort array */ ],
  "start_cursor": "uuid-string",
  "page_size": 100,
  "in_trash": false,
  "result_type": "page" | "data_source"
}
```

### Filter Syntax

**Single property filter:**
```json
{
  "property": "Status",
  "select": { "equals": "Done" }
}
```

**Compound filters (AND logic):**
```json
{
  "and": [
    { "property": "Done", "checkbox": { "equals": true } },
    { "or": [
        { "property": "Tags", "multi_select": { "contains": "A" } },
        { "property": "Tags", "multi_select": { "contains": "B" } }
      ]
    }
  ]
}
```

### Property-Specific Filters

**Text/Title/Rich Text:**
- `equals`, `does_not_equal`, `contains`, `does_not_contain`, `starts_with`, `ends_with`
- `is_empty`, `is_not_empty`

**Number:**
- `equals`, `does_not_equal`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to`
- `is_empty`, `is_not_empty`

**Select/Multi-Select:**
- Select: `equals`, `does_not_equal`
- Multi-Select: `contains`, `does_not_contain`
- Both: `is_empty`, `is_not_empty`

**Date:**
- `equals`, `before`, `after`, `on_or_before`, `on_or_after`
- `this_week`, `past_week`, `past_month`, `past_year`, `next_week`, `next_month`, `next_year`
- `is_empty`, `is_not_empty`

**Checkbox:**
- `equals` (boolean), `does_not_equal` (boolean)

**Relation/People:**
- `contains` (ID), `does_not_contain` (ID)
- `is_empty`, `is_not_empty`

**Timestamp filters:**
```json
{
  "timestamp": "created_time" | "last_edited_time",
  "created_time": { /* date filter */ }
}
```

### Sort Syntax

By property:
```json
[
  {
    "property": "Created",
    "direction": "ascending" | "descending"
  }
]
```

By timestamp:
```json
[
  {
    "timestamp": "created_time" | "last_edited_time",
    "direction": "ascending" | "descending"
  }
]
```

## Response

```json
{
  "type": "page_or_data_source",
  "page_or_data_source": {},
  "object": "list",
  "next_cursor": "uuid-or-null",
  "has_more": false,
  "results": [
    {
      "object": "page",
      "id": "uuid",
      "created_time": "2024-01-01T00:00:00.000Z",
      "last_edited_time": "2024-01-01T00:00:00.000Z",
      "in_trash": false,
      "is_locked": false,
      "url": "https://notion.so/...",
      "public_url": null,
      "parent": { /* parent object */ },
      "properties": { /* property values */ },
      "icon": null,
      "cover": null,
      "created_by": { "id": "uuid", "object": "user" },
      "last_edited_by": { "id": "uuid", "object": "user" }
    }
  ]
}
```

## Complete Example

**Request:**
```typescript
import { Client } from "@notionhq/client";

const notion = new Client({ auth: process.env.NOTION_API_KEY });

const response = await notion.dataSources.query({
  data_source_id: "d9824bdc-8445-4327-be8b-5b47500af6ce",
  filter: {
    property: "Status",
    select: { equals: "Done" }
  },
  sorts: [
    {
      property: "Created",
      direction: "descending"
    }
  ],
  filter_properties: ["title", "status"]
});
```

**Request body (raw JSON):**
```json
{
  "filter": {
    "and": [
      {
        "property": "Status",
        "select": { "equals": "Done" }
      },
      {
        "property": "Created",
        "date": { "on_or_after": "2024-01-01" }
      }
    ]
  },
  "sorts": [
    {
      "property": "Created",
      "direction": "descending"
    }
  ],
  "page_size": 50
}
```

## Key Differences from `databases.query`

This endpoint returns both pages and data sources (for wikis). The documentation notes: "For wikis, instead of directly returning database results, this API returns all data sources that are children."

Use `result_type` filter (`"page"` or `"data_source"`) to isolate results. Performance improves significantly with `filter_properties` for large schemas.

## Error Codes

- **404:** Data source missing or integration lacks access
- **403:** Missing read content capabilities
- **503:** Backend timeout—retry with exponential backoff, smaller `page_size`, or narrower filters
- **429:** Rate limited
- **400:** Invalid request format

## Pagination

Use `next_cursor` from response to fetch additional pages:
```json
{
  "start_cursor": "returned-uuid",
  "page_size": 100
}
```

  2781→type CreatePageBodyParameters = {
  2782→    parent?: {
  2783→        page_id: IdRequest;
  2784→        type?: "page_id";
  2785→    } | {
  2786→        database_id: IdRequest;
  2787→        type?: "database_id";
  2788→    } | {
  2789→        data_source_id: IdRequest;
  2790→        type?: "data_source_id";
  2791→    } | {
  2792→        workspace: true;
  2793→        type?: "workspace";
  2794→    };
  2795→    properties?: Record<string, {
  2796→        title: Array<RichTextItemRequest>;
  2797→        type?: "title";
  2798→    } | {
  2799→        rich_text: Array<RichTextItemRequest>;
  2800→        type?: "rich_text";
  2801→    } | {
  2802→        number: number | null;
  2803→        type?: "number";
  2804→    } | {
  2805→        url: TextRequest | null;
  2806→        type?: "url";
  2807→    } | {
  2808→        select: {
  2809→            id: StringRequest;
  2810→            name?: TextRequest;
  2811→            color?: SelectColor;
  2812→            description?: TextRequest | null;
  2813→        } | {
  2814→            name: TextRequest;
  2815→            id?: StringRequest;
  2816→            color?: SelectColor;
  2817→            description?: TextRequest | null;
  2818→        } | null;
  2819→        type?: "select";
  2820→    } | {
  2821→        multi_select: Array<{
  2822→            id: StringRequest;
  2823→            name?: TextRequest;
  2824→            color?: SelectColor;
  2825→            description?: TextRequest | null;
  2826→        } | {
  2827→            name: TextRequest;
  2828→            id?: StringRequest;
  2829→            color?: SelectColor;
  2830→            description?: TextRequest | null;
  2831→        }>;
  2832→        type?: "multi_select";
  2833→    } | {
  2834→        people: Array<PartialUserObjectRequest | GroupObjectRequest>;
  2835→        type?: "people";
  2836→    } | {
  2837→        email: StringRequest | null;
  2838→        type?: "email";
  2839→    } | {
  2840→        phone_number: StringRequest | null;
  2841→        type?: "phone_number";
  2842→    } | {
  2843→        date: DateRequest | null;
  2844→        type?: "date";
  2845→    } | {
  2846→        checkbox: boolean;
  2847→        type?: "checkbox";
  2848→    } | {
  2849→        relation: Array<RelationItemPropertyValueResponse>;
  2850→        type?: "relation";
  2851→    } | {
  2852→        files: Array<InternalOrExternalFileWithNameRequest | FileUploadWithOptionalNameRequest>;
  2853→        type?: "files";
  2854→    } | {
  2855→        status: {
  2856→            id: StringRequest;
  2857→            name?: TextRequest;
  2858→            color?: SelectColor;
  2859→            description?: TextRequest | null;
  2860→        } | {
  2861→            name: TextRequest;
  2862→            id?: StringRequest;
  2863→            color?: SelectColor;
  2864→            description?: TextRequest | null;
  2865→        } | null;
  2866→        type?: "status";
  2867→    } | {
  2868→        place: {
  2869→            lat: number;
  2870→            lon: number;
  2871→            name?: string | null;
  2872→            address?: string | null;
  2873→            aws_place_id?: string | null;
  2874→            google_place_id?: string | null;
  2875→        } | null;
  2876→        type?: "place";
  2877→    }>;
  2878→    icon?: PageIconRequest | null;
  2879→    cover?: PageCoverRequest | null;
  2880→    content?: Array<BlockObjectRequest>;