Notion Web Utilities API

A comprehensive API for enhancing Notion pages with web content utilities. This API provides several endpoints to extract and update information from web pages to Notion, including favicons, page titles, domain information, and embeds.

This API serves as a bridge between web content and Notion pages, allowing you to:

• Extract favicons from websites and set them as Notion page icons
• Extract page titles from websites and update Notion page titles
• Extract domain information from URLs in Notion pages
• Add URL embeds to Notion pages
• Generate showcases of web content

The API is built using Hono, a lightweight web framework, with modular routes for better organization and maintainability.

/
├── index.tsx         # Main entry point for the API
├── routes/           # Directory for API route modules
│   ├── domain.tsx    # Domain extraction endpoint
│   ├── embed.tsx     # URL embed endpoint
│   ├── favicon.tsx   # Favicon extraction endpoint
│   ├── showcase.tsx  # Content showcase endpoint
│   ├── showcaseHTML.tsx # HTML showcase endpoint
│   ├── test-domain.tsx # Domain testing endpoint
│   └── title.tsx     # Title extraction endpoint
├── utils/            # Utility functions
│   ├── getDomain.tsx # Function to extract domain from URL
│   └── getTitle.tsx  # Function to extract title from URL
└── README.md         # This documentation file

Returns a list of available endpoints.

Example Response:

API Gateway - Available endpoints: /domain, /title, /favicon, /test-domain, /embed, /showcase, /showcase-html

Extracts a favicon from a URL in a Notion page and updates the page icon.

Request Body:

{
  "data": {
    "id": "notion-page-id"
  }
}

Success Response:

{
  "success": true,
  "message": "Favicon found and Notion page updated",
  "pageId": "notion-page-id",
  "url": "https://example.com",
  "faviconUrl": "https://example.com/favicon.ico"
}

Error Response:

{
  "success": false,
  "error": "Failed to retrieve Notion page",
  "message": "Error details",
  "pageId": "notion-page-id"
}

Handles Notion webhooks to extract a favicon from a URL and update the corresponding Notion page with the favicon.

Request Body:

{
  "pageId": "notion-page-id"
}

Success Response:

{
  "success": true,
  "message": "Favicon found and Notion page updated",
  "pageId": "notion-page-id",
  "url": "https://example.com",
  "faviconUrl": "https://example.com/favicon.ico"
}

Extracts the domain from a URL property in a Notion page and updates the Domain property.

Request Body:

{
  "data": {
    "id": "notion-page-id"
  }
}

Success Response: Returns the updated Notion page object.

Test endpoint to verify the domain extraction API is working.

Response:

Hello World!

Extracts the title from a URL in a Notion page and updates the page title.

Request Body:

{
  "data": {
    "id": "notion-page-id"
  }
}

Success Response: Returns the updated Notion page object.

Error Response:

{
  "error": "Error message",
  "stack": "Error stack trace"
}

Test endpoint to verify the title extraction API is working.

Response:

Title Extractor API is running!

Test endpoint for the getTitle function.

Query Parameters:

• url: The URL to extract the title from

Success Response:

{
  "url": "https://example.com",
  "title": "Example Domain"
}

Adds an embed block with the provided URL to a Notion page.

Request Body:

{
  "pageId": "notion-page-id",
  "url": "https://example.com"
}

Endpoints for showcasing content, likely for preview purposes.

The favicon endpoint uses multiple strategies to extract a favicon:

1. First tries Google's Favicon API for reliable results
2. If that fails, tries the standard /favicon.ico path
3. If that fails, it parses the HTML to find favicon link tags
4. Returns the favicon URL and updates the Notion page icon
5. Falls back to a globe emoji (🌐) if no favicon can be found

The title extraction is sophisticated and handles various edge cases:

1. Special handling for YouTube URLs using their oEmbed API
2. Special handling for news sites with anti-scraping measures
3. Multiple fallback strategies including:
   • OpenGraph meta tags
   • Twitter card meta tags
   • Standard title tags
   • Google search results
   • URL slug parsing

Extracts the domain (including protocol) from a URL:

1. Handles URLs without protocol by adding https:// as default
2. Parses the URL to extract the origin (protocol + hostname)
3. Updates the Domain property in the Notion page

This API requires the following environment variable:

• NOTION_API_KEY: Your Notion API integration token

You'll need to create an integration in the Notion workspace and grant it access to the relevant pages or databases.

curl -X POST https://your-api-url/favicon \
  -H "Content-Type: application/json" \
  -d '{"data":{"id":"your-notion-page-id"}}'

curl -X GET "https://your-api-url/title/test?url=https://example.com"

curl -X POST https://your-api-url/title \
  -H "Content-Type: application/json" \
  -d '{"data":{"id":"your-notion-page-id"}}'

To add a new route:

1. Create a new file in the /routes directory
2. Export a Hono router with your endpoint handlers
3. Import and mount the router in index.tsx

Example:

// In /routes/newEndpoint.ts
import { Hono } from "npm:hono@3";

const router = new Hono();

router.get("/", (c) => {
  return c.json({ message: "New endpoint" });
});

export default router;

// In index.tsx
import newEndpoint from "./routes/newEndpoint.tsx";

// Mount the new router
app.route("/new-endpoint", newEndpoint);

The API includes comprehensive error handling:

• Detailed error messages for debugging
• Fallback strategies for common failure scenarios
• Error unwrapping to see original error details

This API integrates with the Notion API to:

1. Retrieve page data including properties like URL and Domain
2. Update page properties with extracted information
3. Set page icons using extracted favicons
4. Add embed blocks to pages

The integration requires a Notion API key and appropriate permissions to access and modify the pages.