Create a database

TypeScript SDK

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

curl --request POST \
  --url https://api.notion.com/v1/databases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "parent": {
    "page_id": "<string>"
  },
  "title": [
    {
      "text": {
        "content": "<string>",
        "link": {
          "url": "<string>"
        }
      },
      "annotations": {
        "bold": true,
        "italic": true,
        "strikethrough": true,
        "underline": true,
        "code": true
      },
      "type": "<string>"
    }
  ],
  "description": [
    {
      "text": {
        "content": "<string>",
        "link": {
          "url": "<string>"
        }
      },
      "annotations": {
        "bold": true,
        "italic": true,
        "strikethrough": true,
        "underline": true,
        "code": true
      },
      "type": "<string>"
    }
  ],
  "is_inline": true,
  "initial_data_source": {
    "properties": {}
  },
  "icon": {
    "file_upload": {
      "id": "<string>"
    },
    "type": "<string>"
  },
  "cover": {
    "file_upload": {
      "id": "<string>"
    },
    "type": "<string>"
  }
}
'

import requests

url = "https://api.notion.com/v1/databases"

payload = {
    "parent": { "page_id": "<string>" },
    "title": [
        {
            "text": {
                "content": "<string>",
                "link": { "url": "<string>" }
            },
            "annotations": {
                "bold": True,
                "italic": True,
                "strikethrough": True,
                "underline": True,
                "code": True
            },
            "type": "<string>"
        }
    ],
    "description": [
        {
            "text": {
                "content": "<string>",
                "link": { "url": "<string>" }
            },
            "annotations": {
                "bold": True,
                "italic": True,
                "strikethrough": True,
                "underline": True,
                "code": True
            },
            "type": "<string>"
        }
    ],
    "is_inline": True,
    "initial_data_source": { "properties": {} },
    "icon": {
        "file_upload": { "id": "<string>" },
        "type": "<string>"
    },
    "cover": {
        "file_upload": { "id": "<string>" },
        "type": "<string>"
    }
}
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/databases",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'parent' => [
        'page_id' => '<string>'
    ],
    'title' => [
        [
                'text' => [
                                'content' => '<string>',
                                'link' => [
                                                                'url' => '<string>'
                                ]
                ],
                'annotations' => [
                                'bold' => true,
                                'italic' => true,
                                'strikethrough' => true,
                                'underline' => true,
                                'code' => true
                ],
                'type' => '<string>'
        ]
    ],
    'description' => [
        [
                'text' => [
                                'content' => '<string>',
                                'link' => [
                                                                'url' => '<string>'
                                ]
                ],
                'annotations' => [
                                'bold' => true,
                                'italic' => true,
                                'strikethrough' => true,
                                'underline' => true,
                                'code' => true
                ],
                'type' => '<string>'
        ]
    ],
    'is_inline' => true,
    'initial_data_source' => [
        'properties' => [
                
        ]
    ],
    'icon' => [
        'file_upload' => [
                'id' => '<string>'
        ],
        'type' => '<string>'
    ],
    'cover' => [
        'file_upload' => [
                'id' => '<string>'
        ],
        'type' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/databases"

	payload := strings.NewReader("{\n  \"parent\": {\n    \"page_id\": \"<string>\"\n  },\n  \"title\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"description\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"is_inline\": true,\n  \"initial_data_source\": {\n    \"properties\": {}\n  },\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.notion.com/v1/databases")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"parent\": {\n    \"page_id\": \"<string>\"\n  },\n  \"title\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"description\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"is_inline\": true,\n  \"initial_data_source\": {\n    \"properties\": {}\n  },\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/databases")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parent\": {\n    \"page_id\": \"<string>\"\n  },\n  \"title\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"description\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"is_inline\": true,\n  \"initial_data_source\": {\n    \"properties\": {}\n  },\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "object": "<unknown>",
  "message": "<string>",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "unauthorized",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "restricted_resource",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "conflict_error",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "rate_limited",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "internal_server_error",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "service_unavailable",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "service_overload",
  "status": "<unknown>",
  "additional_data": {}
}

POST

databases

TypeScript SDK

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

curl --request POST \
  --url https://api.notion.com/v1/databases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "parent": {
    "page_id": "<string>"
  },
  "title": [
    {
      "text": {
        "content": "<string>",
        "link": {
          "url": "<string>"
        }
      },
      "annotations": {
        "bold": true,
        "italic": true,
        "strikethrough": true,
        "underline": true,
        "code": true
      },
      "type": "<string>"
    }
  ],
  "description": [
    {
      "text": {
        "content": "<string>",
        "link": {
          "url": "<string>"
        }
      },
      "annotations": {
        "bold": true,
        "italic": true,
        "strikethrough": true,
        "underline": true,
        "code": true
      },
      "type": "<string>"
    }
  ],
  "is_inline": true,
  "initial_data_source": {
    "properties": {}
  },
  "icon": {
    "file_upload": {
      "id": "<string>"
    },
    "type": "<string>"
  },
  "cover": {
    "file_upload": {
      "id": "<string>"
    },
    "type": "<string>"
  }
}
'

import requests

url = "https://api.notion.com/v1/databases"

payload = {
    "parent": { "page_id": "<string>" },
    "title": [
        {
            "text": {
                "content": "<string>",
                "link": { "url": "<string>" }
            },
            "annotations": {
                "bold": True,
                "italic": True,
                "strikethrough": True,
                "underline": True,
                "code": True
            },
            "type": "<string>"
        }
    ],
    "description": [
        {
            "text": {
                "content": "<string>",
                "link": { "url": "<string>" }
            },
            "annotations": {
                "bold": True,
                "italic": True,
                "strikethrough": True,
                "underline": True,
                "code": True
            },
            "type": "<string>"
        }
    ],
    "is_inline": True,
    "initial_data_source": { "properties": {} },
    "icon": {
        "file_upload": { "id": "<string>" },
        "type": "<string>"
    },
    "cover": {
        "file_upload": { "id": "<string>" },
        "type": "<string>"
    }
}
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/databases",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'parent' => [
        'page_id' => '<string>'
    ],
    'title' => [
        [
                'text' => [
                                'content' => '<string>',
                                'link' => [
                                                                'url' => '<string>'
                                ]
                ],
                'annotations' => [
                                'bold' => true,
                                'italic' => true,
                                'strikethrough' => true,
                                'underline' => true,
                                'code' => true
                ],
                'type' => '<string>'
        ]
    ],
    'description' => [
        [
                'text' => [
                                'content' => '<string>',
                                'link' => [
                                                                'url' => '<string>'
                                ]
                ],
                'annotations' => [
                                'bold' => true,
                                'italic' => true,
                                'strikethrough' => true,
                                'underline' => true,
                                'code' => true
                ],
                'type' => '<string>'
        ]
    ],
    'is_inline' => true,
    'initial_data_source' => [
        'properties' => [
                
        ]
    ],
    'icon' => [
        'file_upload' => [
                'id' => '<string>'
        ],
        'type' => '<string>'
    ],
    'cover' => [
        'file_upload' => [
                'id' => '<string>'
        ],
        'type' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/databases"

	payload := strings.NewReader("{\n  \"parent\": {\n    \"page_id\": \"<string>\"\n  },\n  \"title\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"description\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"is_inline\": true,\n  \"initial_data_source\": {\n    \"properties\": {}\n  },\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.notion.com/v1/databases")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"parent\": {\n    \"page_id\": \"<string>\"\n  },\n  \"title\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"description\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"is_inline\": true,\n  \"initial_data_source\": {\n    \"properties\": {}\n  },\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/databases")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parent\": {\n    \"page_id\": \"<string>\"\n  },\n  \"title\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"description\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"<string>\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"<string>\"\n    }\n  ],\n  \"is_inline\": true,\n  \"initial_data_source\": {\n    \"properties\": {}\n  },\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "object": "<unknown>",
  "message": "<string>",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "unauthorized",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "restricted_resource",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "conflict_error",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "rate_limited",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "internal_server_error",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "service_unavailable",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "service_overload",
  "status": "<unknown>",
  "additional_data": {}
}

Deprecated as of version 2025-09-03This page describes the API for versions up to and including 2022-06-28. In the new 2025-09-03 version, the concepts of databases and data sources were split up, as described in Upgrading to 2025-09-03.Refer to the new APIs instead:

Creates a database as a subpage in the specified parent page, with the specified properties schema. Currently, the parent of a new database must be a Notion page or a wiki database.

Connection capabilitiesThis 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

Option 1
Option 2

object

string

required

The database object type name.

Allowed value: "database"

string<uuid>

required

The ID of the database.

Sort data source entries

Retrieve a database

⌘I

Notion API

Objects

Endpoints

Webhook events

Errors

Authorizations

Headers

Body

Response

​Errors

Authorizations

Headers

Body

Response

Errors