mirror of https://github.com/lfnovo/open-notebook.git synced 2026-04-29 03:50:04 +00:00

2025-07-17 12:38:40 -03:00

20 KiB

Raw Blame History

API Reference

Open Notebook provides a comprehensive REST API for programmatic access to all functionality. This document covers all available endpoints, authentication, request/response formats, and usage examples.

🔗 Base Information

Base URL: http://localhost:5055 (default development)
Content Type: application/json
Authentication: Optional password-based authentication
API Version: v0.2.2

🔐 Authentication

Open Notebook supports optional password-based authentication via the APP_PASSWORD environment variable.

Authentication Header

# If APP_PASSWORD is set
curl -H "Authorization: Bearer YOUR_PASSWORD" \
  http://localhost:5055/api/notebooks

Authentication Responses

401 Unauthorized:

{
  "detail": "Authentication required"
}

📚 Notebooks API

Manage notebook collections and organization.

GET /api/notebooks

Get all notebooks with optional filtering and ordering.

Query Parameters:

archived (boolean, optional): Filter by archived status
order_by (string, optional): Order by field and direction (default: "updated desc")

Response:

[
  {
    "id": "notebook:uuid",
    "name": "My Research Notebook",
    "description": "Research on AI applications",
    "archived": false,
    "created": "2024-01-01T00:00:00Z",
    "updated": "2024-01-01T00:00:00Z"
  }
]

Example:

curl -X GET "http://localhost:5055/api/notebooks?archived=false&order_by=created desc"

POST /api/notebooks

Create a new notebook.

Request Body:

{
  "name": "My New Notebook",
  "description": "Description of the notebook"
}

Response: Same as GET single notebook

Example:

curl -X POST http://localhost:5055/api/notebooks \
  -H "Content-Type: application/json" \
  -d '{"name": "Research Project", "description": "AI research notebook"}'

GET /api/notebooks/{notebook_id}

Get a specific notebook by ID.

Path Parameters:

notebook_id (string): Notebook ID

Response: Same as POST response

PUT /api/notebooks/{notebook_id}

Update a notebook.

Path Parameters:

notebook_id (string): Notebook ID

Request Body (all fields optional):

{
  "name": "Updated Name",
  "description": "Updated description",
  "archived": true
}

Response: Same as GET single notebook

DELETE /api/notebooks/{notebook_id}

Delete a notebook.

Path Parameters:

notebook_id (string): Notebook ID

Response:

{
  "message": "Notebook deleted successfully"
}

📄 Sources API

Manage content sources within notebooks.

POST /api/sources

Create a new source.

Request Body:

{
  "notebook_id": "notebook:uuid",
  "type": "link",
  "url": "https://example.com/article",
  "title": "Optional title",
  "transformations": ["transformation:uuid"],
  "embed": true,
  "delete_source": false
}

Source Types:

link: Web URL
upload: File upload
text: Direct text content

Response:

{
  "id": "source:uuid",
  "title": "Article Title",
  "topics": ["AI", "Machine Learning"],
  "asset": {
    "url": "https://example.com/article"
  },
  "full_text": "Article content...",
  "embedded_chunks": 15,
  "created": "2024-01-01T00:00:00Z",
  "updated": "2024-01-01T00:00:00Z"
}

GET /api/sources

Get all sources with optional filtering.

Query Parameters:

notebook_id (string, optional): Filter by notebook
limit (integer, optional): Maximum results (default: 100)
offset (integer, optional): Pagination offset

Response:

[
  {
    "id": "source:uuid",
    "title": "Article Title",
    "topics": ["AI"],
    "asset": {
      "url": "https://example.com/article"
    },
    "embedded_chunks": 15,
    "insights_count": 3,
    "created": "2024-01-01T00:00:00Z",
    "updated": "2024-01-01T00:00:00Z"
  }
]

GET /api/sources/{source_id}

Get a specific source by ID.

Path Parameters:

source_id (string): Source ID

Response: Same as POST response

PUT /api/sources/{source_id}

Update a source.

Path Parameters:

source_id (string): Source ID

Request Body (all fields optional):

{
  "title": "Updated Title",
  "topics": ["Updated", "Topics"]
}

Response: Same as GET single source

DELETE /api/sources/{source_id}

Delete a source.

Path Parameters:

source_id (string): Source ID

Response:

{
  "message": "Source deleted successfully"
}

📝 Notes API

Manage notes within notebooks.

POST /api/notes

Create a new note.

Request Body:

{
  "title": "Note Title",
  "content": "Note content",
  "note_type": "human",
  "notebook_id": "notebook:uuid"
}

Note Types:

human: Manual note
ai: AI-generated note

Response:

{
  "id": "note:uuid",
  "title": "Note Title",
  "content": "Note content",
  "note_type": "human",
  "created": "2024-01-01T00:00:00Z",
  "updated": "2024-01-01T00:00:00Z"
}

GET /api/notes

Get all notes with optional filtering.

Query Parameters:

notebook_id (string, optional): Filter by notebook
note_type (string, optional): Filter by note type
limit (integer, optional): Maximum results

Response: Array of note objects

GET /api/notes/{note_id}

Get a specific note by ID.

Path Parameters:

note_id (string): Note ID

Response: Same as POST response

PUT /api/notes/{note_id}

Update a note.

Path Parameters:

note_id (string): Note ID

Request Body (all fields optional):

{
  "title": "Updated Title",
  "content": "Updated content",
  "note_type": "ai"
}

Response: Same as GET single note

DELETE /api/notes/{note_id}

Delete a note.

Path Parameters:

note_id (string): Note ID

Response:

{
  "message": "Note deleted successfully"
}

🔍 Search API

Perform full-text and vector search across content.

POST /api/search

Search the knowledge base.

Request Body:

{
  "query": "artificial intelligence",
  "type": "vector",
  "limit": 10,
  "search_sources": true,
  "search_notes": true,
  "minimum_score": 0.2
}

Search Types:

text: Full-text search
vector: Semantic search (requires embedding model)

Response:

{
  "results": [
    {
      "id": "source:uuid",
      "title": "AI Research Paper",
      "content": "Relevant content excerpt...",
      "score": 0.85,
      "type": "source",
      "metadata": {
        "topics": ["AI", "Machine Learning"]
      }
    }
  ],
  "total_count": 1,
  "search_type": "vector"
}

POST /api/search/ask

Ask questions using AI models (streaming response).

Request Body:

{
  "question": "What are the key benefits of AI?",
  "strategy_model": "model:gpt-4o-mini",
  "answer_model": "model:gpt-4o-mini",
  "final_answer_model": "model:gpt-4o-mini"
}

Response: Server-Sent Events (SSE) stream

Stream Events:

// Strategy phase
data: {"type": "strategy", "reasoning": "...", "searches": [...]}

// Individual answers
data: {"type": "answer", "content": "Answer content..."}

// Final answer
data: {"type": "final_answer", "content": "Final synthesized answer..."}

// Completion
data: {"type": "complete", "final_answer": "Final answer..."}

POST /api/search/ask/simple

Ask questions (non-streaming response).

Request Body: Same as streaming version

Response:

{
  "answer": "The key benefits of AI include...",
  "question": "What are the key benefits of AI?"
}

🤖 Models API

Manage AI models and configurations.

GET /api/models

Get all configured models.

Response:

[
  {
    "id": "model:uuid",
    "name": "gpt-4o-mini",
    "provider": "openai",
    "type": "language",
    "created": "2024-01-01T00:00:00Z",
    "updated": "2024-01-01T00:00:00Z"
  }
]

POST /api/models

Create a new model configuration.

Request Body:

{
  "name": "gpt-4o-mini",
  "provider": "openai",
  "type": "language"
}

Model Types:

language: Text generation models
embedding: Vector embedding models
text_to_speech: TTS models
speech_to_text: STT models

Response: Same as GET single model

GET /api/models/{model_id}

Get a specific model by ID.

Path Parameters:

model_id (string): Model ID

Response: Same as POST response

DELETE /api/models/{model_id}

Delete a model configuration.

Path Parameters:

model_id (string): Model ID

Response:

{
  "message": "Model deleted successfully"
}

GET /api/models/defaults

Get default model configurations.

Response:

{
  "default_chat_model": "model:gpt-4o-mini",
  "default_transformation_model": "model:gpt-4o-mini",
  "large_context_model": "model:gpt-4o-mini",
  "default_text_to_speech_model": "model:tts-1",
  "default_speech_to_text_model": "model:whisper-1",
  "default_embedding_model": "model:text-embedding-3-small",
  "default_tools_model": "model:gpt-4o-mini"
}

🔧 Transformations API

Manage content transformations and AI-powered analysis.

GET /api/transformations

Get all transformations.

Response:

[
  {
    "id": "transformation:uuid",
    "name": "summarize",
    "title": "Summarize Content",
    "description": "Create a concise summary",
    "prompt": "Summarize the following content...",
    "apply_default": true,
    "created": "2024-01-01T00:00:00Z",
    "updated": "2024-01-01T00:00:00Z"
  }
]

POST /api/transformations

Create a new transformation.

Request Body:

{
  "name": "custom_analysis",
  "title": "Custom Analysis",
  "description": "Perform custom content analysis",
  "prompt": "Analyze the following content for key themes...",
  "apply_default": false
}

Response: Same as GET single transformation

GET /api/transformations/{transformation_id}

Get a specific transformation by ID.

Path Parameters:

transformation_id (string): Transformation ID

Response: Same as POST response

PUT /api/transformations/{transformation_id}

Update a transformation.

Path Parameters:

transformation_id (string): Transformation ID

Request Body (all fields optional):

{
  "name": "updated_name",
  "title": "Updated Title",
  "description": "Updated description",
  "prompt": "Updated prompt...",
  "apply_default": true
}

Response: Same as GET single transformation

DELETE /api/transformations/{transformation_id}

Delete a transformation.

Path Parameters:

transformation_id (string): Transformation ID

Response:

{
  "message": "Transformation deleted successfully"
}

POST /api/transformations/execute

Execute a transformation on content.

Request Body:

{
  "transformation_id": "transformation:uuid",
  "input_text": "Content to transform...",
  "model_id": "model:gpt-4o-mini"
}

Response:

{
  "output": "Transformed content...",
  "transformation_id": "transformation:uuid",
  "model_id": "model:gpt-4o-mini"
}

📊 Insights API

Manage AI-generated insights for sources.

GET /api/sources/{source_id}/insights

Get insights for a specific source.

Path Parameters:

source_id (string): Source ID

Response:

[
  {
    "id": "insight:uuid",
    "source_id": "source:uuid",
    "insight_type": "summary",
    "content": "This source discusses...",
    "created": "2024-01-01T00:00:00Z",
    "updated": "2024-01-01T00:00:00Z"
  }
]

POST /api/sources/{source_id}/insights

Create a new insight for a source.

Path Parameters:

source_id (string): Source ID

Request Body:

{
  "transformation_id": "transformation:uuid",
  "model_id": "model:gpt-4o-mini"
}

Response: Same as GET insight

POST /api/insights/{insight_id}/save-as-note

Save an insight as a note.

Path Parameters:

insight_id (string): Insight ID

Request Body:

{
  "notebook_id": "notebook:uuid"
}

Response:

{
  "note_id": "note:uuid",
  "message": "Insight saved as note successfully"
}

🎙️ Podcasts API

Generate professional multi-speaker podcasts.

GET /api/episode-profiles

Get all episode profiles.

Response:

[
  {
    "id": "episode_profile:uuid",
    "name": "tech_discussion",
    "description": "Technical discussion between 2 experts",
    "speaker_config": "tech_experts",
    "outline_provider": "openai",
    "outline_model": "gpt-4o-mini",
    "transcript_provider": "openai",
    "transcript_model": "gpt-4o-mini",
    "default_briefing": "Create an engaging technical discussion...",
    "num_segments": 5,
    "created": "2024-01-01T00:00:00Z",
    "updated": "2024-01-01T00:00:00Z"
  }
]

GET /api/speaker-profiles

Get all speaker profiles.

Response:

[
  {
    "id": "speaker_profile:uuid",
    "name": "tech_experts",
    "description": "Two technical experts for tech discussions",
    "tts_provider": "openai",
    "tts_model": "tts-1",
    "speakers": [
      {
        "name": "Dr. Alex Chen",
        "voice_id": "nova",
        "backstory": "Senior AI researcher...",
        "personality": "Analytical, clear communicator..."
      }
    ],
    "created": "2024-01-01T00:00:00Z",
    "updated": "2024-01-01T00:00:00Z"
  }
]

POST /api/podcasts

Create a new podcast episode.

Request Body:

{
  "name": "AI Discussion Episode",
  "briefing": "Discuss the latest AI developments...",
  "episode_profile_id": "episode_profile:uuid",
  "source_ids": ["source:uuid1", "source:uuid2"],
  "note_ids": ["note:uuid1"]
}

Response:

{
  "id": "episode:uuid",
  "name": "AI Discussion Episode",
  "briefing": "Discuss the latest AI developments...",
  "episode_profile": {...},
  "speaker_profile": {...},
  "command": "command:uuid",
  "created": "2024-01-01T00:00:00Z",
  "updated": "2024-01-01T00:00:00Z"
}

GET /api/podcasts/{episode_id}

Get a specific podcast episode.

Path Parameters:

episode_id (string): Episode ID

Response: Same as POST response

GET /api/podcasts/{episode_id}/audio

Download the generated audio file.

Path Parameters:

episode_id (string): Episode ID

Response: Audio file download (MP3 format)

🎛️ Settings API

Manage application settings and configuration.

GET /api/settings

Get current application settings.

Response:

{
  "default_content_processing_engine_doc": "docling",
  "default_content_processing_engine_url": "firecrawl",
  "default_embedding_option": "auto",
  "auto_delete_files": "false",
  "youtube_preferred_languages": ["en", "es"]
}

PUT /api/settings

Update application settings.

Request Body (all fields optional):

{
  "default_content_processing_engine_doc": "docling",
  "default_content_processing_engine_url": "firecrawl",
  "default_embedding_option": "auto",
  "auto_delete_files": "true",
  "youtube_preferred_languages": ["en", "fr", "de"]
}

Response: Same as GET response

📐 Context API

Manage context configuration for AI operations.

POST /api/context

Get context information for a notebook.

Request Body:

{
  "notebook_id": "notebook:uuid",
  "context_config": {
    "sources": {
      "source:uuid1": "full",
      "source:uuid2": "summary"
    },
    "notes": {
      "note:uuid1": "full"
    }
  }
}

Context Levels:

full: Include complete content
summary: Include summary only
exclude: Exclude from context

Response:

{
  "notebook_id": "notebook:uuid",
  "sources": [
    {
      "id": "source:uuid",
      "title": "Source Title",
      "content": "Source content...",
      "inclusion_level": "full"
    }
  ],
  "notes": [
    {
      "id": "note:uuid",
      "title": "Note Title",
      "content": "Note content...",
      "inclusion_level": "full"
    }
  ],
  "total_tokens": 1500
}

🔨 Commands API

Monitor and manage background jobs.

GET /api/commands

Get all commands (background jobs).

Query Parameters:

status (string, optional): Filter by status
limit (integer, optional): Maximum results

Response:

[
  {
    "id": "command:uuid",
    "name": "podcast_generation",
    "status": "completed",
    "progress": 100,
    "result": {...},
    "error": null,
    "created": "2024-01-01T00:00:00Z",
    "updated": "2024-01-01T00:00:00Z"
  }
]

GET /api/commands/{command_id}

Get a specific command by ID.

Path Parameters:

command_id (string): Command ID

Response: Same as array item above

DELETE /api/commands/{command_id}

Cancel/delete a command.

Path Parameters:

command_id (string): Command ID

Response:

{
  "message": "Command deleted successfully"
}

🏷️ Embedding API

Manage vector embeddings for content.

POST /api/embed

Generate embeddings for an item.

Request Body:

{
  "item_id": "source:uuid",
  "item_type": "source"
}

Item Types:

source: Source content
note: Note content

Response:

{
  "success": true,
  "message": "Embedding generated successfully",
  "item_id": "source:uuid",
  "item_type": "source"
}

🚨 Error Responses

Common Error Codes

400 Bad Request:

{
  "detail": "Invalid input data"
}

401 Unauthorized:

{
  "detail": "Authentication required"
}

404 Not Found:

{
  "detail": "Resource not found"
}

422 Validation Error:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

500 Internal Server Error:

{
  "detail": "Internal server error occurred"
}

📋 Usage Examples

Complete Workflow Example

# 1. Create a notebook
NOTEBOOK_ID=$(curl -X POST http://localhost:5055/api/notebooks \
  -H "Content-Type: application/json" \
  -d '{"name": "AI Research", "description": "Research on AI applications"}' \
  | jq -r '.id')

# 2. Add a source
SOURCE_ID=$(curl -X POST http://localhost:5055/api/sources \
  -H "Content-Type: application/json" \
  -d "{\"notebook_id\": \"$NOTEBOOK_ID\", \"type\": \"link\", \"url\": \"https://example.com/ai-article\", \"embed\": true}" \
  | jq -r '.id')

# 3. Create a model
MODEL_ID=$(curl -X POST http://localhost:5055/api/models \
  -H "Content-Type: application/json" \
  -d '{"name": "gpt-4o-mini", "provider": "openai", "type": "language"}' \
  | jq -r '.id')

# 4. Search for content
curl -X POST http://localhost:5055/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "artificial intelligence", "type": "vector", "limit": 5}'

# 5. Ask a question
curl -X POST http://localhost:5055/api/search/ask/simple \
  -H "Content-Type: application/json" \
  -d "{\"question\": \"What are the main AI applications?\", \"strategy_model\": \"$MODEL_ID\", \"answer_model\": \"$MODEL_ID\", \"final_answer_model\": \"$MODEL_ID\"}"

Podcast Generation Example

# 1. Get episode profiles
curl -X GET http://localhost:5055/api/episode-profiles

# 2. Create a podcast
EPISODE_ID=$(curl -X POST http://localhost:5055/api/podcasts \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"AI Discussion\", \"briefing\": \"Discuss AI trends\", \"episode_profile_id\": \"episode_profile:tech_discussion\", \"source_ids\": [\"$SOURCE_ID\"]}" \
  | jq -r '.id')

# 3. Check command status
curl -X GET http://localhost:5055/api/commands

# 4. Download audio when ready
curl -X GET http://localhost:5055/api/podcasts/$EPISODE_ID/audio -o podcast.mp3

📡 WebSocket Support

Currently, Open Notebook uses Server-Sent Events (SSE) for real-time updates in the Ask endpoint. WebSocket support may be added in future versions for more interactive features.

📈 Rate Limiting

The API currently doesn't enforce rate limiting, but it's recommended to implement rate limiting in production deployments to prevent abuse.

🔄 Versioning

The API uses semantic versioning. Breaking changes will increment the major version number. The current API version is included in the OpenAPI documentation at /docs.

This API reference provides comprehensive coverage of Open Notebook's REST API. For additional examples and integration patterns, check the GitHub repository and join our Discord community.

20 KiB Raw Blame History

API Reference

🔗 Base Information

🔐 Authentication

Authentication Header

Authentication Responses

📚 Notebooks API

GET /api/notebooks

POST /api/notebooks

GET /api/notebooks/{notebook_id}

PUT /api/notebooks/{notebook_id}

DELETE /api/notebooks/{notebook_id}

📄 Sources API

POST /api/sources

GET /api/sources

GET /api/sources/{source_id}

PUT /api/sources/{source_id}

DELETE /api/sources/{source_id}

📝 Notes API

POST /api/notes

GET /api/notes

GET /api/notes/{note_id}

PUT /api/notes/{note_id}

DELETE /api/notes/{note_id}

🔍 Search API

POST /api/search

POST /api/search/ask

POST /api/search/ask/simple

🤖 Models API

GET /api/models

POST /api/models

GET /api/models/{model_id}

DELETE /api/models/{model_id}

GET /api/models/defaults

🔧 Transformations API

GET /api/transformations

POST /api/transformations

GET /api/transformations/{transformation_id}

PUT /api/transformations/{transformation_id}

DELETE /api/transformations/{transformation_id}

POST /api/transformations/execute

📊 Insights API

GET /api/sources/{source_id}/insights

POST /api/sources/{source_id}/insights

POST /api/insights/{insight_id}/save-as-note

🎙️ Podcasts API

GET /api/episode-profiles

GET /api/speaker-profiles

POST /api/podcasts

GET /api/podcasts/{episode_id}

GET /api/podcasts/{episode_id}/audio

🎛️ Settings API

GET /api/settings

PUT /api/settings

📐 Context API

POST /api/context

🔨 Commands API

GET /api/commands

GET /api/commands/{command_id}

DELETE /api/commands/{command_id}

🏷️ Embedding API

POST /api/embed

🚨 Error Responses

Common Error Codes

📋 Usage Examples

Complete Workflow Example

Podcast Generation Example

📡 WebSocket Support

📈 Rate Limiting

🔄 Versioning

20 KiB

Raw Blame History