Create a database

Create a database and its initial data source.

POST /v1/databases

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" } }]
})

200

{
  "object": "database",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Creates a database as a subpage in the specified parent page, or as a private page at the workspace level, with the specified properties schema set on its initial_data_source. Currently, the parent of a new database must be a Notion page (page_id type) or a wiki database.

Use this endpoint to create a database, its first data source, and its first table view, all in one API call. Then, if you want to add a second data source, use the Create a data source API with a version of at least 2025-09-03, and provide the database_id as the id returned by the database create response.

For a complete reference on what properties are available, see Data source properties. After creating the database, to update one of its child data sources’ properties, use the Update a data source API.

Typed databases

Pass database_type to build the database from one of Notion’s canonical schemas instead of your own. Notion sets the properties and the metadata that marks the database as that type, so the result matches a database of that type created in the Notion app. Supported values are tasks, projects, and skills.

Each type creates a fixed set of properties:

database_type	Properties
tasks	Task name (title), Assignee (people), Status (status), Due (date)
projects	Project name (title), Owner (people), Dates (date), Status (status)
skills	Skill name (title), Description (rich_text), Files (files), Tags (multi_select), Created by (created_by)

Property names follow the language preference of the user who owns the integration token. Internal integrations have no owner, so they get English names. Call Retrieve a data source on the data source returned in the create response to read the exact names, along with the status option names and IDs, before writing pages. To add properties of your own on top of a typed schema, use Update a data source.

database_type can’t be combined with initial_data_source, because a typed database always uses Notion’s schema. Sending both returns a 400 HTTP response. If you omit title, the database is named after its type. The created database and its data source both report the type back as database_type.

Connection capabilities

This endpoint requires a connection to have insert content capabilities. Attempting to call this API without insert content capabilities will return an HTTP response with a 403 status code. For more information on connection capabilities, see the capabilities guide.

Errors

Returns a 404 if the specified parent page does not exist, or if the connection does not have access to the parent page.

Returns a 400 if the request is incorrectly formatted, or a 429 HTTP response if the request exceeds the request limits.

Note: Each Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version · enum<string> · required

The API version to use for this request. The latest version is 2026-03-11.

Available options: 2026-03-11

Body

application/json

parent · Page Id · object · required

The parent page or workspace where the database will be created.

Page Id

Workspace

Show child attributes

title · (Text · object | Mention · object | Equation · object)[]

The title of the database.

Maximum array length: 100

Text

Mention

Equation

Show child attributes

description · (Text · object | Mention · object | Equation · object)[]

The description of the database.

Maximum array length: 100

Text

Mention

Equation

Show child attributes

is_inline · boolean

Whether the database should be displayed inline in the parent page. Defaults to false.

initial_data_source · object

Initial data source configuration for the database.

Show child attributes

database_type · enum<string>

Create a typed database with Notion's canonical schema. One of tasks, projects, or skills. Cannot be combined with initial_data_source. When title is omitted, the database is named after the type.

Available options: tasks, projects, skills

icon · File Upload · object

The icon for the database.

File Upload

Emoji

External

Custom Emoji

Icon

Show child attributes

cover · File Upload · object

The cover image for the database.

File Upload

External

Show child attributes

Response

200

application/json

Option 1

Option 2

object · string · required

The database object type name.

Allowed value: "database"

id · string<uuid> · required

The ID of the database.