Create a database

{
  "Result": {
    "value": "{\n\t\"object\": \"database\",\n\t\"id\": \"248104cd-477e-80fd-b757-e945d38000bd\",\n\t\"title\": [\n\t\t{\n\t\t\t\"type\": \"text\",\n\t\t\t\"text\": {\n\t\t\t\t\"content\": \"My Task Tracker\",\n\t\t\t\t\"link\": null\n\t\t\t},\n\t\t\t\"annotations\": {\n\t\t\t\t\"bold\": false,\n\t\t\t\t\"italic\": false,\n\t\t\t\t\"strikethrough\": false,\n\t\t\t\t\"underline\": false,\n\t\t\t\t\"code\": false,\n\t\t\t\t\"color\": \"default\"\n\t\t\t},\n\t\t\t\"plain_text\": \"My Task Tracker\",\n\t\t\t\"href\": null\n\t\t}\n\t],\n\t\"parent\": {\n\t\t\"type\": \"page_id\",\n\t\t\"page_id\": \"255104cd-477e-808c-b279-d39ab803a7d2\"\n\t},\n\t\"is_inline\": false,\n\t\"in_trash\": false,\n\t\"created_time\": \"2025-08-07T10:11:07.504-07:00\",\n\t\"last_edited_time\": \"2025-08-10T15:53:11.386-07:00\",\n\t\"data_sources\": [\n\t\t{\n\t\t\t\"id\": \"248104cd-477e-80af-bc30-000bd28de8f9\",\n\t\t\t\"name\": \"My Task Tracker\"\n\t\t}\n\t],\n\t\"icon\": null,\n\t\"cover\": null,\n\t\"developer_survey\": \"https://example.com/xyz\",\n\t\"request_id\": \"2f788b44-abf3-4809-aa4c-dd40734fed0b\"\n}"
  }
}

Create a database and its initial data source.

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.

Integration capabilities

This endpoint requires an integration 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 integration capabilities, see the capabilities guide.

Limitations

Creating new status database properties is currently not supported.

Errors

Returns a 404 if the specified parent page does not exist, or if the integration 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.

Request

This endpoint expects an object.

parentobjectRequired

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

initial_data_sourceobjectOptional

Initial data source configuration for the database.

titlelist of objectsOptional

The title of the database.

descriptionlist of objectsOptional

The description of the database.

iconobjectOptional

The icon for the database.

coverobjectOptional

The cover image for the database.

Response

200

objectstringOptional

idstringOptional

titlelist of objectsOptional

parentobjectOptional

is_inlinebooleanOptionalDefaults to true

in_trashbooleanOptionalDefaults to true

created_timestringOptional

last_edited_timestringOptional

data_sourceslist of objectsOptional

iconanyOptional

coveranyOptional

developer_surveystringOptional

request_idstringOptional

Errors

400

Bad Request Error

Errors

Headers

Request

Response

Errors