Open Notebook
Drive Open Notebook’s REST API from an agent to create research notebooks, attach sources, and manage notes on localhost.
Overview
Open-notebook is an agent skill most often used in Idea research (also Build integrations) that implements Open Notebook REST operations for notebooks, sources, and notes against a local API server.
Install
npx skills add https://github.com/k-dense-ai/scientific-agent-skills --skill open-notebookWhat is this skill?
- Documents base URL `http://localhost:5055/api` plus Swagger at `/docs` and ReDoc at `/redoc`
- Notebook lifecycle: list, create, get, update, delete with archived and sort query params
- Delete preview endpoint before destructive notebook removal
- Optional `OPEN_NOTEBOOK_PASSWORD` auth with documented public exception routes
- Response shapes include `source_count` and `note_count` on notebook list/get
- Default API base documented as `http://localhost:5055/api`
- Six auth-exempt routes listed including `/health`, `/docs`, `/redoc`, `/openapi.json`
Adoption & trust: 550 installs on skills.sh; 27.6k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent needs to file papers and notes into Open Notebook but you only have UI knowledge—not stable endpoint paths and payloads.
Who is it for?
Researchers running Open Notebook locally who want Claude or Cursor agents to sync sources and notes through the official API.
Skip if: Builders without a running Open Notebook service or those who only need generic markdown notes outside a notebook product.
When should I use this skill?
User or workflow needs Open Notebook notebook CRUD, source/note operations, or API auth against a running instance.
What do I get? / Deliverables
The agent creates and updates notebooks, queries counts, and performs guarded deletes via documented `/api/notebooks` routes.
- Created or updated notebook records via REST
- Query results with source and note counts
- Safe delete flows using delete-preview when removing notebooks
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Literature and source organization belongs on the idea/research shelf before implementation commitments. The skill is an API contract for notebook CRUD—not generic note-taking prose—so research subphase is the canonical home.
Where it fits
Spin up a named notebook per hypothesis and track source_count as papers are ingested.
Wire an agent pipeline to POST new notebooks when a literature scrape completes.
Use Swagger `/docs` routes as ground truth while implementing automated note sync.
Archive finished notebooks via API after turning findings into public write-ups.
How it compares
Local REST integration for Open Notebook—not a standalone Zotero importer or cloud Notion skill.
Common Questions / FAQ
Who is open-notebook for?
Indie researchers and scientific-agent users who host Open Notebook and want agents to read/write notebooks via its API.
When should I use open-notebook?
During idea/research when organizing sources, during build/integrations when wiring agents to your notebook backend, and during grow/content when republishing structured notes.
Is open-notebook safe to install?
It implies network calls to your own server; review the Security Audits panel on this Prism page and lock down password auth and localhost exposure in production-like setups.
SKILL.md
READMESKILL.md - Open Notebook
# Open Notebook API Reference ## Base URL ``` http://localhost:5055/api ``` Interactive API documentation is available at `http://localhost:5055/docs` (Swagger UI) and `http://localhost:5055/redoc` (ReDoc). ## Authentication If `OPEN_NOTEBOOK_PASSWORD` is configured, include the password in requests. The following routes are excluded from authentication: `/`, `/health`, `/docs`, `/openapi.json`, `/redoc`, `/api/auth/status`, `/api/config`. --- ## Notebooks ### List Notebooks ``` GET /api/notebooks ``` **Query Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `archived` | boolean | Filter by archived status | | `order_by` | string | Sort field (default: `updated_at`) | **Response:** Array of notebook objects with `source_count` and `note_count`. ### Create Notebook ``` POST /api/notebooks ``` **Request Body:** ```json { "name": "My Research", "description": "Optional description" } ``` ### Get Notebook ``` GET /api/notebooks/{notebook_id} ``` ### Update Notebook ``` PUT /api/notebooks/{notebook_id} ``` **Request Body:** ```json { "name": "Updated Name", "description": "Updated description", "archived": false } ``` ### Delete Notebook ``` DELETE /api/notebooks/{notebook_id} ``` **Query Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `delete_sources` | boolean | Also delete exclusive sources (default: false) | ### Delete Preview ``` GET /api/notebooks/{notebook_id}/delete-preview ``` Returns counts of notes and sources that would be affected by deletion. ### Link Source to Notebook ``` POST /api/notebooks/{notebook_id}/sources/{source_id} ``` Idempotent operation to associate a source with a notebook. ### Unlink Source from Notebook ``` DELETE /api/notebooks/{notebook_id}/sources/{source_id} ``` --- ## Sources ### List Sources ``` GET /api/sources ``` **Query Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `notebook_id` | string | Filter by notebook | | `limit` | integer | Number of results | | `offset` | integer | Pagination offset | | `order_by` | string | Sort field | ### Create Source ``` POST /api/sources ``` Accepts multipart form data for file uploads or JSON for URL/text sources. **Form Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `file` | file | Upload file (PDF, DOCX, audio, video) | | `url` | string | Web URL to ingest | | `text` | string | Raw text content | | `notebook_id` | string | Associate with notebook | | `process_async` | boolean | Process asynchronously (default: true) | ### Create Source (JSON) ``` POST /api/sources/json ``` Legacy JSON-based endpoint for source creation. ### Get Source ``` GET /api/sources/{source_id} ``` ### Get Source Status ``` GET /api/sources/{source_id}/status ``` Poll processing status for asynchronously ingested sources. ### Update Source ``` PUT /api/sources/{source_id} ``` **Request Body:** ```json { "title": "Updated Title", "topic": "Updated topic" } ``` ### Delete Source ``` DELETE /api/sources/{source_id} ``` ### Download Source File ``` GET /api/sources/{source_id}/download ``` Returns the original uploaded file. ### Check Source File ``` HEAD /api/sources/{source_id}/download ``` ### Retry Failed Source ``` POST /api/sources/{source_id}/retry ``` Requeue a failed source for processing. ### Get Source Insights ``` GET /api/sources/{source_id}/insights ``` Retrieve AI-generated insights for a source. --- ## Notes ### List Notes ``` GET /api/notes ``` **Query Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `notebook_id` | string | Filter by notebook | ### Create Note ``` POST /api/notes ``` **Request Body:** ```json { "title": "My Note", "content": "Note content...", "note_type": "human", "notebook_id": "notebook:abc123" } ``` `note_type` must be `"human"` or `"ai"`. AI notes without titles get aut