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": "<string>",
  "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.

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

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.