# How to Integrate Open Notebook with Other Tools

> Learn to integrate Open Notebook with other tools using its unified REST API. Connect your self-contained backend API with automation scripts, CI pipelines, and custom front-ends easily.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: how-to-guide
- Published: 2026-06-08

---

Integrating Open Notebook with other tools starts with its unified REST API. The project is built as a **self‑contained backend API** using FastAPI, exposing a full‑featured HTTP interface. All UI components, the native web client, and any external application interact with the same endpoints, which makes it straightforward to connect Open Notebook to automation scripts, CI pipelines, custom front‑ends, or third‑party services.

Because every layer is deliberately decoupled, you can **consume the API directly**, **use the provided Python client**, or **re‑implement a thin wrapper in any language** such as Node, Go, or Bash. The API follows standard OpenAPI conventions, and the live spec is available at `http://<host>:5055/docs` once the server is running.

## Open Notebook Integration Architecture

The following layers form the stable, language‑agnostic contract you interact with when you integrate Open Notebook with other tools:

| Layer | Purpose | Primary source files |
|------|---------|----------------------|
| **API server** – FastAPI app that routes requests, performs authentication and delegates to service classes. | Entry point for all external calls. | [[`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py)](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) |
| **Routers** – Modular collections of endpoints (notebooks, sources, notes, chat, embeddings, models, etc.). | Granular, version‑stable HTTP contract. | [[`api/routers/notebooks.py`](https://github.com/lfnovo/open-notebook/blob/main/api/routers/notebooks.py)](https://github.com/lfnovo/open-notebook/blob/main/api/routers/notebooks.py), [[`api/routers/sources.py`](https://github.com/lfnovo/open-notebook/blob/main/api/routers/sources.py)](https://github.com/lfnovo/open-notebook/blob/main/api/routers/sources.py), [[`api/routers/chat.py`](https://github.com/lfnovo/open-notebook/blob/main/api/routers/chat.py)](https://github.com/lfnovo/open-notebook/blob/main/api/routers/chat.py) |
| **Service layer** – Business logic that talks to the database, runs LangGraph workflows and invokes AI providers. | Keeps the routers thin and reusable from any client. | [[`api/notebook_service.py`](https://github.com/lfnovo/open-notebook/blob/main/api/notebook_service.py)](https://github.com/lfnovo/open-notebook/blob/main/api/notebook_service.py), [[`api/sources_service.py`](https://github.com/lfnovo/open-notebook/blob/main/api/sources_service.py)](https://github.com/lfnovo/open-notebook/blob/main/api/sources_service.py), [[`api/chat_service.py`](https://github.com/lfnovo/open-notebook/blob/main/api/chat_service.py)](https://github.com/lfnovo/open-notebook/blob/main/api/chat_service.py) |
| **Python client** – Thin wrapper around the HTTP API, auto‑generating request URLs and handling auth tokens. | Ideal for scripts, notebooks, or other Python projects. | [[`api/client.py`](https://github.com/lfnovo/open-notebook/blob/main/api/client.py)](https://github.com/lfnovo/open-notebook/blob/main/api/client.py) |
| **AI provisioning** – Centralised model/credential discovery via the Esperanto library. | External tools can rely on the same model selection logic. | [[`open_notebook/ai/provision.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/provision.py)](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/provision.py) |
| **Database (SurrealDB)** – Async driver stores notebooks, sources, vectors and embeddings. | All CRUD operations ultimately hit this layer. | [[`open_notebook/database/repository.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/database/repository.py)](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/database/repository.py) |

## Step‑by‑Step Workflow to Integrate Open Notebook with Other Tools

A typical integration follows these five stages:

1. **Authentication** – By default the dev server uses a simple password middleware ([`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py)). Production deployments can replace this with OAuth/JWT. Pass the token (or basic auth header) with every request.
2. **Notebook creation** – `POST /notebooks` creates a logical container for research.
3. **Add sources** – `POST /sources` uploads PDFs, URLs, or raw text. The backend extracts, chunks, embeds and stores the content automatically via [[`open_notebook/graphs/source.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/source.py)](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/source.py).
4. **Run a workflow** – Trigger a LangGraph workflow (e.g., chat, ask, transformation) via endpoints under `/chat`, `/ask`, or `/transformations`. The workflow engine (`open_notebook/graphs/*.py`) runs asynchronously and returns a job ID you can poll.
5. **Consume results** – Retrieve notes, search results, or generated podcast audio through their dedicated routers.

All of these steps are fully documented in the OpenAPI spec and can be scripted.

## Practical Code Examples to Integrate Open Notebook with Other Tools

The snippets below demonstrate how to authenticate and execute common operations using `curl`, the official Python wrapper, and Node.js.

### Quick‑Start with `curl`

```bash

# 1 Authenticate (replace <PASSWORD> with your dev password)

TOKEN=$(curl -s -X POST http://localhost:5055/auth/login \
       -H "Content-Type: application/json" \
       -d '{"username":"admin","password":"<PASSWORD>"}' | jq -r .access_token)

# 2 Create a notebook

curl -X POST http://localhost:5055/notebooks \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"title":"Research on AI Safety","description":"My notes"}'

# 3 Add a PDF source (file must be base64‑encoded)

BASE64_PDF=$(base64 my_paper.pdf)
curl -X POST http://localhost:5055/sources \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"notebook_id":"<NOTEBOOK_ID>","type":"pdf","content_base64":"'"$BASE64_PDF"'"}'

# 4 Ask a question (LangGraph ask workflow)

curl -X POST http://localhost:5055/ask \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"notebook_id":"<NOTEBOOK_ID>","question":"What are the main findings?"}'

```

### Python Client (Recommended for Automation)

```python
from open_notebook_api import OpenNotebookClient  # generated from api/client.py

# Initialise the client (host defaults to http://localhost:5055)

client = OpenNotebookClient(base_url="http://localhost:5055", username="admin", password="my-secret")

# Create a notebook

nb = client.create_notebook(title="AI Safety Repo", description="Collected papers")
print("Notebook ID:", nb.id)

# Upload a URL source (the backend will fetch & extract)

source = client.create_source(
    notebook_id=nb.id,
    type="url",
    content="https://arxiv.org/pdf/2206.01091.pdf"
)
print("Source ID:", source.id)

# Run a chat query

response = client.chat(
    notebook_id=nb.id,
    messages=[{"role": "user", "content": "Summarize the key ideas"}]
)
print("Chat answer:", response.answer)

```

### Node.js Example (using `node-fetch`)

```js
const fetch = require('node-fetch');

async function callAPI() {
  // Login and get token
  const loginRes = await fetch('http://localhost:5055/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username: 'admin', password': '<PASSWORD>' })
  });
  const { access_token: token } = await loginRes.json();

  // Create notebook
  const nbRes = await fetch('http://localhost:5055/notebooks', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ title: 'My Notebook', description: 'Demo' })
  });
  const notebook = await nbRes.json();
  console.log('Notebook ID:', notebook.id);
}
callAPI();

```

## Key Files That Enable Open Notebook Integration

| File | Role | Link |
|------|------|------|
| [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) | FastAPI entry point, registers all routers and middleware. | [api/main.py](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) |
| `api/routers/*.py` | Individual REST endpoints (notebooks, sources, chat, embeddings, etc.). | [api/routers/notebooks.py](https://github.com/lfnovo/open-notebook/blob/main/api/routers/notebooks.py) |
| [`api/client.py`](https://github.com/lfnovo/open-notebook/blob/main/api/client.py) | Auto‑generated Python wrapper for the OpenAPI spec. | [api/client.py](https://github.com/lfnovo/open-notebook/blob/main/api/client.py) |
| [`open_notebook/ai/provision.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/provision.py) | Handles multi‑provider model discovery & credential management (Esperanto). | [open_notebook/ai/provision.py](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/provision.py) |
| `open_notebook/graphs/*.py` | LangGraph workflow definitions (source ingestion, chat, ask, transformations). | [open_notebook/graphs/chat.py](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/chat.py) |
| [`open_notebook/database/repository.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/database/repository.py) | Async SurrealDB repository abstraction used by services. | [open_notebook/database/repository.py](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/database/repository.py) |
| [`docs/5-CONFIGURATION/mcp-integration.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/mcp-integration.md) | Documentation on connecting external MCP clients (Claude Desktop, VS Code, etc.). | [docs/5-CONFIGURATION/mcp-integration.md](https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/mcp-integration.md) |

## Getting Started with Your Own Open Notebook Integration

When you integrate Open Notebook with other tools, you gain access to semantic search, AI‑augmented note generation, podcast creation, and multi‑model orchestration from any external system. Start by reviewing the live OpenAPI spec at `http://<host>:5055/docs`, then choose the layer that best fits your stack— direct HTTP calls for universal compatibility, or the Python client for rapid automation.