# 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 auto-generated titles. ### Get Note ``` GET /api/notes/{note_id} ``` ### Update Note ``` PUT /api/notes/{note_id} ``` **Request Body:** ```json { "title": "Updated Title", "content": "Updated content", "note_type": "human" } ``` ### Delete Note ``` DELETE /api/notes/{note_id} ``` --- ## Chat ### List Sessions ``` GET /api/chat/sessions ``` **Query Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `notebook_id` | string | Filter by notebook | ### Create Session ``` POST /api/chat/sessions ``` **Request Body:** ```json { "notebook_id": "notebook:abc123", "title": "Discussion Topic", "model_override": "optional_model_id" } ``` ### Get Session ``` GET /api/chat/sessions/{session_id} ``` Returns session details with message history. ### Update Session ``` PUT /api/chat/sessions/{session_id} ``` ### Delete Session ``` DELETE /api/chat/sessions/{session_id} ``` ### Execute Chat ``` POST /api/chat/execute ``` **Request Body:** ```json { "session_id": "chat_session:abc123", "message": "Your question here", "context": { "include_sources": true, "include_notes": true }, "model_override": "optional_model_id" } ``` ### Build Context ``` POST /api/chat/context ``` Build contextual data from sources and notes for a chat session. --- ## Search ### Search Knowledge Base ``` POST /api/search ``` **Request Body:** ```json { "query": "search terms", "search_type": "vector", "limit": 10, "source_ids": [], "note_ids": [], "min_similarity": 0.7 } ``` `search_type` can be `"vector"` (requires embedding model) or `"text"` (keyword matching). ### Ask with Streaming ``` POST /api/search/ask ``` Returns Server-Sent Events with AI-generated answers based on knowledge base content. ### Ask Simple ``` POST /api/search/ask/simple ``` Non-streaming version that returns a complete response. --- ## Podcasts ### Generate Podcast ``` POST /api/podcasts/generate ``` **Request Body:** ```json { "notebook_id": "notebook:abc123", "episode_profile_id": "episode_profile:xyz", "speaker_profile_ids": ["speaker:a", "speaker:b"] } ``` Returns a `job_id` for tracking generation progress. ### Get Job Status ``` GET /api/podcasts/jobs/{job_id} ``` ### List Episodes ``` GET /api/podcasts/episodes ``` ### Get Episode ``` GET /api/podcasts/episodes/{episode_id} ``` ### Get Episode Audio ``` GET /api/podcasts/episodes/{episode_id}/audio ``` Streams the podcast audio file. ### Retry Failed Episode ``` POST /api/podcasts/episodes/{episode_id}/retry ``` ### Delete Episode ``` DELETE /api/podcasts/episodes/{episode_id} ``` --- ## Transformations ### List Transformations ``` GET /api/transformations ``` ### Create Transformation ``` POST /api/transformations ``` **Request Body:** ```json { "name": "summarize", "title": "Summarize Content", "description": "Generate a concise summary", "prompt": "Summarize the following text...", "apply_default": false } ``` ### Execute Transformation ``` POST /api/transformations/execute ``` **Request Body:** ```json { "transformation_id": "transformation:abc", "input_text": "Text to transform...", "model_id": "model:xyz" } ``` ### Get Default Prompt ``` GET /api/transformations/default-prompt ``` ### Update Default Prompt ``` PUT /api/transformations/default-prompt ``` ### Get Transformation ``` GET /api/transformations/{transformation_id} ``` ### Update Transformation ``` PUT /api/transformations/{transformation_id} ``` ### Delete Transformation ``` DELETE /api/transformations/{transformation_id} ``` --- ## Models ### List Models ``` GET /api/models ``` **Query Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `model_type` | string | Filter by type (llm, embedding, stt, tts) | ### Create Model ``` POST /api/models ``` ### Delete Model ``` DELETE /api/models/{model_id} ``` ### Test Model ``` POST /api/models/{model_id}/test ``` ### Get Default Models ``` GET /api/models/defaults ``` Returns default model assignments for seven service slots: chat, transformation, embedding, speech-to-text, text-to-speech, podcast, and summary. ### Update Default Models ``` PUT /api/models/defaults ``` ### Get Providers ``` GET /api/models/providers ``` ### Discover Models ``` GET /api/models/discover/{provider} ``` ### Sync Models (Single Provider) ``` POST /api/models/sync/{provider} ``` ### Sync All Models ``` POST /api/models/sync ``` ### Auto-Assign Defaults ``` POST /api/models/auto-assign ``` Automatically populate empty default model slots using provider priority rankings. ### Get Model Count ``` GET /api/models/count/{provider} ``` ### Get Models by Provider ``` GET /api/models/by-provider/{provider} ``` --- ## Credentials ### Get Status ``` GET /api/credentials/status ``` ### Get Environment Status ``` GET /api/credentials/env-status ``` ### List Credentials ``` GET /api/credentials ``` **Query Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `provider` | string | Filter by provider | ### List by Provider ``` GET /api/credentials/by-provider/{provider} ``` ### Create Credential ``` POST /api/credentials ``` **Request Body:** ```json { "provider": "openai", "name": "My OpenAI Key", "api_key": "sk-...", "base_url": null } ``` ### Get Credential ``` GET /api/credentials/{credential_id} ``` Note: API key values are never returned. ### Update Credential ``` PUT /api/credentials/{credential_id} ``` ### Delete Credential ``` DELETE /api/credentials/{credential_id} ``` ### Test Credential ``` POST /api/credentials/{credential_id}/test ``` ### Discover Models via Credential ``` POST /api/credentials/{credential_id}/discover ``` ### Register Models via Credential ``` POST /api/credentials/{credential_id}/register-models ``` --- ## Error Responses The API returns standard HTTP status codes with JSON error bodies: | Status | Meaning | |--------|---------| | 400 | Invalid input | | 401 | Authentication required | | 404 | Resource not found | | 422 | Configuration error | | 429 | Rate limited | | 500 | Internal server error | | 502 | External service error | **Error Response Format:** ```json { "detail": "Description of the error" } ```