# Create database

Part of **Notion**. Route queries via `POST https://www.company-skill.com/api/route`.

## What You Want to Do

You want to create a new Notion database with a defined structure (properties like text, select, relation, etc.) and optionally configure views or integrate it into an automated workflow. This includes both one-time manual setups and programmatic creation for external systems.

**Typical User Questions**:
- How to create a database using Notion API?
- How to define a database schema in Notion?

## Decision Tree

Pick the best path for your situation:

- **If** you need to automate database creation or integrate with external systems using code → Use **Create via API** (go to *notion/notion-database*)
- **If** you're setting up a one-off database manually in the Notion app with immediate visual feedback → Use **Define schema visually** (go to *notion/notion-database*)
- **If** you require webhook event handling for database changes (e.g., created, schema updated) → Use **Create via API**
- **Otherwise (default)** → **Define schema visually**, as it’s faster for simple, non-automated use cases and requires no coding or API setup.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Create via API | Automated or programmatic database creation with full control over schema and properties. | medium | Yes | Yes | Requires `Notion-Version: 2026-03-11` header and Bearer token auth | `notion/api/notion-database` |
| Define schema visually | Interactive setup using Notion's UI schema builder without code. | low | No | No | Uses `/database` slash command and **Properties button** to add fields like **Select property** or **Relation property** | `notion/guide/notion-database` |

## Path Details

### Path 1: Create via API

**Best For**: Automated or programmatic database creation with full control over schema and properties.

**Brief Description**: The Notion Database Management API is a RESTful service that lets you create, update, and query databases via HTTP requests. You must include the `Notion-Version` header and authenticate with a Bearer token. Use the `@notionhq/client` SDK or raw HTTP calls to define properties like **Rollup property** or **Multi-select property** programmatically.

**Key technical facts**:
- Auth method: Header: Authorization: Bearer <token>, where <token> is your auth token.
- Prerequisites: Notion Integration Token, Integration shared with target database, Notion-Version: 2026-03-11 header for all requests, @notionhq/client SDK (JavaScript/TypeScript) or direct HTTP calls

**When to Use**:
- Need automated or programmatic database creation with full control over schema and properties
- Building integrations that synchronize external data with Notion
- Requiring webhook event handling for database changes (created, deleted, schema updated)
- Need to manage large datasets with pagination (up to 10,000 results per query)

**When NOT to Use**:
- User prefers visual interface without writing code
- Simple one-time database setup without automation needs
- No access to Notion Integration Token or API permissions
- Need immediate visual feedback during schema design

**Known Limitations**:
- Requires sharing integration with specific database to access it (403 error otherwise)
- Maximum schema size limit of 50KB for database properties
- Rate limits of 100 requests per minute per API key
- Property type conversions may not be supported after creation (e.g., formula to select)
- Database ID must be 32 characters alphanumeric string or UUID format depending on context

### Path 2: Define schema visually

**Best For**: Interactive setup using Notion's UI schema builder without code.

**Brief Description**: Use Notion’s web interface to create databases via the `/database` slash command or "+ New page" flow. Configure structure using the **Properties button**, then click **+ Add a property** to define fields like **Select property**, **Multi-select property**, **Relation property**, or **Rollup property**. Every new database starts with an **Untitled title** that you can rename.

**Key technical facts**:
- Prerequisites: Active Notion account, Edit permissions in the target workspace

**When to Use**:
- Interactive setup using Notion's UI schema builder without code
- Simple one-time database creation with immediate visual feedback
- User has edit permissions but no API integration access
- Designing database structure through trial-and-error with real-time preview

**When NOT to Use**:
- Need automated or programmatic database creation
- Building external integrations that sync data with Notion
- Require webhook notifications for database changes
- Managing large-scale deployments across multiple workspaces

**Known Limitations**:
- Cannot change property type after creation without deleting and recreating (data loss risk)
- No support for programmatic automation or scripting
- Limited to databases within the same workspace for Relation properties
- Performance may degrade with very large schemas (50+ properties)
- No webhook event handling or external integration capabilities

## FAQ

Q: Which path should I start with?
A: Start with **Define schema visually** if you’re creating a single database for personal or team use and don’t need automation. Use **Create via API** only if you’re building an integration or need to create databases programmatically.

Q: What if I need to change a **Select property** to a **Relation property** after creating the database using the visual method?
A: You’ll hit a limitation: property types cannot be changed after creation without deleting the property (and losing data). The API also restricts some type conversions (e.g., formula to select), so plan your schema carefully in either path.

Q: What if I exceed the **rate limits** of 100 requests per minute but chose the API path?
A: Your API calls will be throttled, returning 429 errors. You’ll need to implement retry logic with backoff or reduce request frequency—this doesn’t apply to the visual path since it has no rate limits.

Q: Can I use **Relation property** across workspaces when defining schema visually?
A: No—you’re limited to databases within the same workspace. The API also enforces this restriction, so cross-workspace relations aren’t supported in either path.

Q: What happens if I forget to include the **Notion-Version header** when using the API?
A: Your request will fail, likely with a 400 error. The header `Notion-Version: 2026-03-11` is mandatory for all API calls, as noted in prerequisites.

Q: Does the visual path support **Rollup property** configuration?
A: Yes—you can add a **Rollup property** via **+ Add a property** in the UI, just like **Select property** or **Multi-select property**. However, complex rollup formulas may be harder to debug without API-level logging.

Q: 如果我需要自动化但选择了“Define schema visually”，会怎样？
A: 你将无法实现自动化创建或同步外部数据，因为该路径不支持程序化操作或脚本。

Q: 如果我没有 Notion Integration Token 但选择了“Create via API”，会怎样？
A: 你会收到 403 错误，因为 API 路径要求集成已共享到目标数据库，否则无法访问。

## Related queries

create notion database, manage notion database, notion database setup, how to create notion database, define database schema in notion, notion api database, notion database programmatically, notion database automation, notion database ui, notion database without code, notion database integration, no

---
Part of [Notion](https://www.company-skill.com/p/notion.md) · https://www.company-skill.com/llms.txt