The options for creating a page.
The data for creating the page.
The parent of the page (must include data_source_id, page_id, or database_id (database_id is deprecated and will not work in databases with more than one data source)).
Optionalproperties?: ObjectThe properties of the page.
Optionalicon?: ObjectThe icon of the page.
Optionalcover?: ObjectThe cover of the page.
Optionalchildren?: Object[]An array of child blocks to add to the page.
Optionalclient?: ObjectThe Notion client object. Either this or apiCall must be provided.
OptionalapiCall?: FunctionA custom function for making API calls. Receives { type: 'create_page', data } as argument. Either this or client must be provided.
OptionalgetPage?: FunctionA function to extract the page data from the API response. If you're passing a custom apiCall function, you should pass a getPage function as well.
OptionalgetResults?: FunctionA function to extract results from the API response when appending blocks. Enables the append() method to append all child blocks in the request. If you're passing a custom apiCall function, you should pass a getResults function as well.
OptionaltemplateWaitMs?: numberMilliseconds to wait after page creation when using templates, before appending children. This allows time for Notion's template processing to complete.
OptionalonTemplatePageCreated?: FunctionOptional callback function called after page creation but before appending children when using templates. Receives { page, template, fallbackWaitMs } as parameter, where page is the created Notion page object, template is the template object used to create the page, and fallbackWaitMs is the value of templateWaitMs. Can throw an error to stop execution and prevent children appending. Alternatively, you can pass a number to templateWaitMs, which the callback can use in case it fails to directly verify the template is ready.
OptionalskipAutoAppendOnTemplate?: booleanIf true, returns children to caller instead of auto-appending them when using templates. Useful for manual control over template verification.
An object containing the API response for page creation and, if applicable, the result of appending children. When skipAutoAppendOnTemplate is true and templates are used, returns { apiResponse, pendingChildren, pageId } instead.
// Using with Notion SDK client
const notion = new Client({ auth: NOTION_TOKEN });
const page = createNotion()
.parentDataSource("your-data-source-id")
.title("Name", "Charmander")
.icon("https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/4.png")
.richText("Category", "Lizard Pokémon")
.quote("Obviously prefers hot places. When it rains, steam is said to spout from the tip of its tail.")
.build()
const result = await request.pages.create({
data: page.content,
client: notion
});
// Using with custom API call function (using ky)
import ky from 'ky';
const NOTION_TOKEN = 'your-notion-token';
const NOTION_VERSION = '2025-09-03';
const apiCall = async ({ type, data }) => {
if (type === 'create_page') {
return await ky.post('https://api.notion.com/v1/pages', {
json: data,
headers: {
'Authorization': `Bearer ${NOTION_TOKEN}`,
'Notion-Version': NOTION_VERSION,
},
}).json();
} else if (type === 'append_blocks') {
// createPage calls this when appending children
const { block_id, children, after } = data;
return await ky.patch(
`https://api.notion.com/v1/blocks/${block_id}/children`,
{
json: { children, ...(after && { after }) },
headers: {
'Authorization': `Bearer ${NOTION_TOKEN}`,
'Notion-Version': NOTION_VERSION,
},
}
).json();
}
};
const page = createNotion()
.parentDataSource("your-data-source-id")
.title("Name", "Squirtle")
.icon("https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/7.png")
.richText("Category", "Tiny Turtle Pokémon")
.quote("After birth, its back swells and hardens into a shell. Powerfully sprays foam from its mouth.")
.build()
const result = await request.pages.create({
data: page.content,
apiCall,
getPage: (response) => response,
getResults: (response) => response.results
});
// Using with templates
const templatePage = createNotionBuilder()
.parentDataSource("your-data-source-id")
.template("default") // or template_id
.title("Name", "Task from Template")
.paragraph("This content will be appended after template processing")
.build()
const result = await request.pages.create({
data: templatePage.content,
client: notion,
templateWaitMs: 2000, // Wait 2 seconds for template processing
onTemplatePageCreated: async ({ page }) => {
console.log(`Template page created: ${page.id}`);
// Optional: Verify template content is ready
// page.parent contains data_source_id or database_id if needed
}
});
// Using skipAutoAppendOnTemplate for manual control
const result = await request.pages.create({
data: templatePage.content,
client: notion,
skipAutoAppendOnTemplate: true
});
// Manually append children after verifying template is ready
if (result.pendingChildren && result.pendingChildren.length > 0) {
await request.blocks.children.append({
block_id: result.pageId,
children: result.pendingChildren,
client: notion
});
}
Creates a new page in Notion and optionally appends child blocks to it. Includes as many child blocks as possible in the initial request. Uses request.blocks.children.append() for all remaining child blocks, so it can handle nested blocks to any level.