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 token_v2 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 your Notion workspace. You can usually find this in the URL when browsing your Notion workspace (it's the part after your domain and before the first page ID, often a UUID).
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.

Running Locally (without Docker)

Ensure you have Python 3.10+ installed.
Install dependencies:
```
pip install -r requirements.txt
```

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

NOTION_COOKIE="your_cookie_value_here"
NOTION_SPACE_ID="your_space_id_here"
# PROXY_AUTH_TOKEN="your_secure_token" # Optional, defaults to default_token

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.

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.

Ensure you have Docker and Docker Compose installed.
Make sure your .env file exists in the project root with your NOTION_COOKIE, NOTION_SPACE_ID, and optionally PROXY_AUTH_TOKEN and NOTION_ACTIVE_USER_HEADER. 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.
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).
The application will be accessible locally at http://localhost:8139.

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.

Build the Docker image:
```
docker build -t notion-api-bridge .
```
Run the Docker container: Replace "your_cookie_value" and "your_space_id" with your actual Notion credentials.
```
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
  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.

Deploying to Hugging Face Spaces

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

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).
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.
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 your Notion Space ID.
- 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. Hugging Face will securely inject these secrets as environment variables into your running container.
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).

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).

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
      }'