README.md

metadata

title: Notion API Bridge
emoji: 🌉
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit

OpenAI to Notion API Bridge

This project provides a FastAPI application that acts as a bridge between OpenAI-compatible API calls and the Notion API, allowing you to interact with Notion using standard OpenAI tools and libraries.

Environment Variables

The application requires the following environment variables to be set:

• NOTION_COOKIE: Your Notion complete cookie value. This is used for authentication with the Notion API. You can typically find this in your browser's developer tools while logged into Notion.

• NOTION_SPACE_ID: The ID of the Notion Space you want the API to interact with (x-notion-space-id in header).

• PROXY_AUTH_TOKEN (Optional): The Bearer token required for authentication to access the API endpoints. If not set, it defaults to default_token.

• NOTION_ACTIVE_USER_HEADER (Optional): If set, its value will be used for the x-notion-active-user-header in requests sent to the Notion API. If not set or empty, the header is omitted.

• PROXY_URL (Optional): URL of a proxy server to route all network connections through. If not set or empty, no proxy is used. Supports both HTTP and SOCKS5 proxies. Examples:

  • HTTP proxy: http://proxy.example.com:8080
  • SOCKS5 proxy: socks5://proxy.example.com:1080

  This proxy configuration affects all network connections made by the application through the Playwright browser automation.

Running Locally (without Docker)

1. Ensure you have Python 3.10+ installed.
2. Install dependencies:

   pip install -r requirements.txt
   

3. Create a .env file in the project root with your NOTION_COOKIE:

   NOTION_COOKIE="your_cookie_value_here"
   NOTION_SPACE_ID="your_space_id_here"
   # PROXY_AUTH_TOKEN="your_secure_token" # Optional, defaults to default_token
   # NOTION_ACTIVE_USER_HEADER="your_user_id" # Optional
   # PROXY_URL="http://proxy.example.com:8080" # Optional, for HTTP proxy
   # PROXY_URL="socks5://proxy.example.com:1080" # Optional, for SOCKS5 proxy
   

4. Run the application using Uvicorn:

   uvicorn main:app --reload --port 7860
   

   The server will be available at http://localhost:7860. You will need to provide the correct token (either the default default_token or the one set in .env) via an Authorization: Bearer <token> header. The NOTION_SPACE_ID will be loaded from the .env file.

Running with Docker Compose (Recommended for Local Dev)

This method uses the docker-compose.yml file for a streamlined local development setup. It automatically builds the image if needed and loads environment variables directly from your .env file.

1. Ensure you have Docker and Docker Compose installed.
2. Make sure your .env file exists in the project root with your NOTION_COOKIE, NOTION_SPACE_ID, and optionally PROXY_AUTH_TOKEN, NOTION_ACTIVE_USER_HEADER, and PROXY_URL. If PROXY_AUTH_TOKEN is not in the .env file, the default default_token will be used. If NOTION_ACTIVE_USER_HEADER is not set or empty, the corresponding header will not be sent. If PROXY_URL is not set or empty, no proxy will be used.
3. Run the following command in the project root:

   docker-compose up --build -d
   

   • --build: Rebuilds the image if the Dockerfile or context has changed.
   • -d: Runs the container in detached mode (in the background).
4. The application will be accessible locally at http://localhost:8139. Environment variables like NOTION_COOKIE and NOTION_SPACE_ID will be loaded automatically from the .env file.

To stop the service, run:

docker-compose down

Running with Docker Command (Manual)

This method involves building and running the Docker container manually, passing environment variables directly in the command.

1. Build the Docker image:

   docker build -t notion-api-bridge .
   

2. Run the Docker container: Replace "your_cookie_value" with your actual Notion cookie.

   docker run -p 7860:7860 \
     -e NOTION_COOKIE="your_cookie_value" \
     -e NOTION_SPACE_ID="your_space_id" \
     -e PROXY_AUTH_TOKEN="your_token" \ # Set your desired token here
     # -e NOTION_ACTIVE_USER_HEADER="your_user_id" \ # Optional: Set the active user header
     # -e PROXY_URL="http://proxy.example.com:8080" \ # Optional: Set proxy URL
     notion-api-bridge
   

   The server will be available at http://localhost:7860 (or whichever host port you mapped to the container's 7860). You will need to use the token provided in the -e PROXY_AUTH_TOKEN flag via an Authorization: Bearer <token> header for authentication. The NOTION_SPACE_ID is passed directly via the -e flag.

Deploying to Hugging Face Spaces

This application is designed to be easily deployed as a Docker Space on Hugging Face.

1. Create a new Space: Go to Hugging Face and create a new Space, selecting "Docker" as the Space SDK. Choose a name (e.g., notion-api-bridge).

2. Upload Files: Upload the Dockerfile, main.py, models.py, and requirements.txt to your Space repository. You can do this via the web interface or by cloning the repository and pushing the files. Do not upload your .env file.

3. Add Secrets: In your Space settings, navigate to the "Secrets" section. Add two secrets:

   • NOTION_COOKIE: Paste your Notion token_v2 cookie value.
   • NOTION_SPACE_ID: Paste the ID of the target Notion Space.
   • PROXY_AUTH_TOKEN: Paste the desired Bearer token for API authentication (e.g., a strong, generated token). If you omit this, the default default_token will be used.
   • NOTION_ACTIVE_USER_HEADER (Optional): Paste the user ID to be sent in the x-notion-active-user-header. If omitted, the header will not be sent.
   • PROXY_URL (Optional): Paste the proxy server URL if you need to route connections through a proxy. Supports both HTTP (e.g., http://proxy.example.com:8080) and SOCKS5 (e.g., socks5://proxy.example.com:1080) proxies. Hugging Face will securely inject these secrets as environment variables into your running container.

4. Deployment: Hugging Face Spaces will automatically build the Docker image from your Dockerfile and run the container. It detects applications running on port 7860 (as specified in the Dockerfile and metadata).

5. Accessing the API: Once the Space is running, you can access the API endpoint at the Space's public URL, providing the token via an Authorization: Bearer <token> header. The token must match the PROXY_AUTH_TOKEN secret you set (or the default default_token). The NOTION_SPACE_ID will be used automatically based on the secret you configured.

   Example using curl (replace your_token and URL):

   # Example for Hugging Face Space (using token from HF Secret)
   # Replace YOUR_HF_TOKEN with the value you set in the PROXY_AUTH_TOKEN secret
   curl -X POST https://your-username-your-space-name.hf.space/v1/chat/completions \
     -H "Authorization: Bearer YOUR_HF_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "model": "notion-model", # Specify a Notion model like "openai-gpt-4.1"
           "messages": [{"role": "user", "content": "Summarize this document."}],
           "stream": false,
           "notion_model": "openai-gpt-4.1" # Required field for Notion
         }'
   
   # Example for Localhost (using default token 'default_token')
   # If you set a different token in .env or via -e, use that instead.
   curl -X POST http://localhost:7860/v1/chat/completions \
     -H "Authorization: Bearer default_token" \
     -H "Content-Type: application/json" \
     -d '{
           "model": "notion-model",
           "messages": [{"role": "user", "content": "What is the capital of France?"}],
           "stream": true,
           "notion_model": "anthropic-sonnet-4" # Required field for Notion
         }'