Documentation Index
Fetch the complete documentation index at: https://mintlify.com/makenotion/notion-sdk-js/llms.txt
Use this file to discover all available pages before exploring further.
The Notion SDK provides utilities to extract properly formatted UUIDs from Notion URLs or raw ID strings.
Extracts a Notion ID from a Notion URL or returns the input if it’s already a valid ID. This is the primary function that all other extraction helpers use internally.
Signature
function extractNotionId(urlOrId: string): string | null
Parameters
urlOrId - A Notion URL or ID string
Returns
- The extracted UUID in standard format (with hyphens) or
null if invalid
Features
- Accepts URLs, compact IDs (32 hex chars), or formatted UUIDs
- Prioritizes path IDs over query parameters to avoid extracting view IDs instead of database IDs
- Returns IDs in standard UUID format:
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- Case-insensitive
Examples
import { extractNotionId } from "@notionhq/client"
// Database URL with view ID - extracts database ID, not view ID
const id1 = extractNotionId(
"https://notion.so/workspace/DB-abc123def456789012345678901234ab?v=viewid123"
)
// Returns: "abc123de-f456-7890-1234-5678901234ab" (database ID)
// Already formatted UUID
const id2 = extractNotionId("12345678-1234-1234-1234-123456789abc")
// Returns: "12345678-1234-1234-1234-123456789abc"
// Compact UUID (no hyphens)
const id3 = extractNotionId("12345678123412341234123456789abc")
// Returns: "12345678-1234-1234-1234-123456789abc"
// Page URL
const id4 = extractNotionId(
"https://www.notion.so/My-Page-Title-a1b2c3d4e5f6789012345678901234ab"
)
// Returns: "a1b2c3d4-e5f6-7890-1234-5678901234ab"
// Invalid input
const id5 = extractNotionId("not-a-valid-id")
// Returns: null
extractNotionId.
Signature
function extractPageId(pageUrl: string): string | null
Example
import { extractPageId } from "@notionhq/client"
const pageId = extractPageId(
"https://www.notion.so/My-Page-a1b2c3d4e5f6789012345678901234ab"
)
// Returns: "a1b2c3d4-e5f6-7890-1234-5678901234ab"
// Use with the SDK
const page = await notion.pages.retrieve({ page_id: pageId })
extractNotionId.
Signature
function extractDatabaseId(databaseUrl: string): string | null
Example
import { extractDatabaseId } from "@notionhq/client"
const databaseId = extractDatabaseId(
"https://www.notion.so/workspace/My-Database-abc123def456789012345678901234ab?v=viewid"
)
// Returns: "abc123de-f456-7890-1234-5678901234ab"
// Use with the SDK
const database = await notion.databases.retrieve({ database_id: databaseId })
#block-<id> or #<id> patterns.
Signature
function extractBlockId(urlWithBlock: string): string | null
Example
import { extractBlockId } from "@notionhq/client"
// URL with block fragment
const blockId1 = extractBlockId(
"https://www.notion.so/My-Page-a1b2c3d4#block-123456789012345678901234567890ab"
)
// Returns: "12345678-9012-3456-7890-1234567890ab"
// URL with simple fragment
const blockId2 = extractBlockId(
"https://www.notion.so/My-Page-a1b2c3d4#123456789012345678901234567890ab"
)
// Returns: "12345678-9012-3456-7890-1234567890ab"
// Use with the SDK
const block = await notion.blocks.retrieve({ block_id: blockId1 })
Common Use Cases
Converting User-Provided URLs
When users share Notion URLs, use these helpers to extract the ID:
import { extractPageId } from "@notionhq/client"
const userInput = "https://www.notion.so/My-Page-abc123..."
const pageId = extractPageId(userInput)
if (pageId) {
const page = await notion.pages.retrieve({ page_id: pageId })
console.log(page)
} else {
console.error("Invalid Notion URL")
}
Handling Database URLs with View Parameters
The extractors prioritize database IDs over view IDs:
import { extractDatabaseId } from "@notionhq/client"
// This URL contains both a database ID and a view ID
const url = "https://notion.so/DB-abc123...?v=view456..."
// Correctly extracts the database ID, not the view ID
const databaseId = extractDatabaseId(url)
const results = await notion.databases.query({ database_id: databaseId })
import { extractNotionId } from "@notionhq/client"
const inputs = [
"https://notion.so/page-abc123...",
"abc123def456789012345678901234ab",
"abc123de-f456-7890-1234-5678901234ab",
]
const ids = inputs.map(extractNotionId).filter(id => id !== null)
console.log(ids) // All in standard UUID format
Return Value
All extraction functions return:
- A string in standard UUID format (
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) if successful
null if the input is invalid or doesn’t contain a valid Notion ID
Always check for null before using the extracted ID.