---
title: Notion API Bridge
emoji: 🌉
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit # Or choose another appropriate license if preferred
# Add any other relevant tags or configuration if needed
---
# 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:
    ```bash
    pip install -r requirements.txt
    ```
3.  Create a `.env` file in the project root with your `NOTION_COOKIE`:
    ```dotenv
    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:
    ```bash
    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:
    ```bash
    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:
```bash
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:**
    ```bash
    docker build -t notion-api-bridge .
    ```
2.  **Run the Docker container:**
    Replace `"your_cookie_value"` with your actual Notion cookie.
    ```bash
    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):**
    ```bash
    # 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
          }'