Open Notebook API Reference

Reviewed 2026-09-30 against v1.14.0 and main commit 3127f14ea9dbb519f0e4ddc64a0742ca644ba6ef. Routes below are from the official router source, request/response models, and podcast service. Source verification and local mocked tests are not authenticated end-to-end tests. The installed instance's /openapi.json is authoritative for its version.

Transport and authentication

Base: http://localhost:5055/api. Tables use full /api paths. Interactive docs are /docs and /redoc on the backend origin, not below /api. If OPEN_NOTEBOOK_PASSWORD is set on the server, send Authorization: Bearer <instance-password> on every protected request, including downloads. Otherwise authentication is disabled. The encryption key is for server credential storage; it is neither a bearer token nor a client requirement.

The middleware configuration excludes /, /health, /docs, /openapi.json, /redoc, /api/auth/status, and /api/config; CORS OPTIONS is also exempt. There is no OAuth token exchange in this password mechanism.

Use finite HTTP timeouts, check status before parsing, preserve record IDs returned by the server (notebook:..., source:..., model:...), and URL-encode path segments. Mutating requests have no documented idempotency-key contract; do not blindly retry a timed-out creation or generation request. Check for an existing record/job first. Most responses are JSON with success status 200; credential creation is 201.

Notebooks

Notebook objects have id, name, description, archived, created, updated, source_count, and note_count. There is no updated_at sort field or delete_sources query parameter. The source-link handler's existing-reference lookup uses the reverse edge direction from its insertion at this reviewed version; its advertised idempotence is therefore not treated as a reliable contract here.

Sources

Form contract:

Source objects include id, nullable title, topics, asset (file_path, url), full_text, embedded, embedded_chunks, nullable file_available, created, updated, nullable command_id, status, processing_info, and notebooks. List summaries omit full_text/notebooks and include insights_count. Paginate until a short/empty page, using fixed sort order; offset pages can shift if the collection is modified during traversal.

For asynchronous processing, expect new/queued/running/completed/failed states; other worker states can appear. Only completed is a positive job result. Unknown/missing statuses must not imply success. A synchronous/legacy source may have status=null and no command: fetch it and inspect text. Successful extraction is distinct from embedding completion. Inspect errors before an explicit retry; the reviewed retry handler can swallow its own active-job check, so clients should refuse active jobs.

Notes

Use human or ai for note_type. An AI note with content and no title invokes a model to generate the title. Responses have id, nullable title, content, note_type, created, updated, and nullable command_id for background work.

Chat

A session has id, title, nullable notebook_id, created, updated, nullable message_count and model_override. Messages use id, type (human/ai), content, nullable timestamp—not a role key. Execute returns updated history; take the last AI message rather than expecting a top-level response string.

Explicit context configuration:

{
  "notebook_id": "notebook:example",
  "context_config": {
    "sources": {"source:example": "full content"},
    "notes": {}
  }
}

Source states are full content, insights, not in context; notes support full content or exclusion. {} requests all notebook items with short context; {"sources": {}, "notes": {}} selects none. The server can skip unavailable IDs without failing the request. Check returned IDs/content and token count. Pass only the returned context member into Execute. include_sources/include_notes and top-level source/note ID lists are not a context-building protocol.

Search and Ask

{
  "query": "treatment allocation",
  "type": "vector",
  "limit": 10,
  "search_sources": true,
  "search_notes": true,
  "minimum_score": 0.2
}

type defaults to text; vector mode requires a configured default embedding model and embedded content. limit is 1–1000 (default 100), minimum_score is 0–1 (default 0.2). total_count is the length of the returned list, not the total number of matching corpus records. Results are dictionaries; vector results can include similarity. No offset/cursor pagination is exposed by this search endpoint.

The v1.14.0 schema has no notebook or source filters. search_type, source_ids, note_ids, and min_similarity in request bodies can be silently ignored. Current main adds notebook_id and notebook_ids (max 50) to both Search and Ask; omit/empty means global. This is a post-v1.14.0 addition, verified in main's schema at the reviewed commit. Check the deployed schema before relying on scope; never silently retry globally.

Ask's three model values must be registered model:... IDs; using the same language model for all three is allowed. Ask also requires an embedding model. Streaming messages are data: <JSON> events with type: strategy, answer, final_answer, complete, or error. Read content for answer events, final_answer on complete, and message on error. An HTTP 200 stream can still end in an error event.

Podcasts

{
  "episode_profile": "Existing episode profile name",
  "speaker_profile": "Existing speaker profile name",
  "episode_name": "Methods review",
  "content": "Reviewed research text to narrate"
}

episode_profile, speaker_profile, and episode_name are required. Profiles are selected by name, not episode_profile_id/speaker_profile_ids. content or notebook_id supplies material; briefing_suffix is optional. Prefer explicit reviewed content: the notebook-only path has an upstream fallback to a string/ID if context gathering fails. Poll with a deadline and handle failed/error/unknown states; do not access a top-level episode_id on the job response.

Transformations

Transformation records add id, created, and updated to their input fields. Executing raw text returns output; it does not automatically create a persisted note or insight. Preserve provenance when saving generated text.

Models

Model records have id, name, provider, type, nullable credential, created, updated. Use registered IDs for chat/Ask/default assignments, provider model names for model registration. Default slots are default_chat_model, default_transformation_model, large_context_model, default_text_to_speech_model, default_speech_to_text_model, default_embedding_model, default_tools_model. There are no podcast or summary slots. Explicitly assign optional speech models; auto-assign does not populate them. Verify provider data flow before assigning defaults.

Credentials

Settings include modalities, api_key, base_url; Azure has endpoint, api_version; separate endpoints may use endpoint_llm, endpoint_embedding, endpoint_stt, endpoint_tts; Vertex uses project, location, credentials_path; Ollama supports num_ctx. Validate the chosen provider in the instance schema; requirements differ by provider. Stored API keys are encrypted server-side and never returned. Responses expose has_api_key, model_count, and nullable decryption_error plus non-secret configuration and timestamps. Do not print credential request bodies or copy keys into examples.

Errors

Always check HTTP status before parsing a success shape. FastAPI validation uses 422 with a detail list of field errors; other handlers commonly return a detail string. Not every failure has the same JSON structure. Expected categories include 400 invalid input, 401 missing/invalid instance password, 403 denied file access, 404 missing resource, 413 oversized upload, 422 schema/configuration failure, 429 provider rate limits, 500 backend/job submission errors, and 502 provider errors. A queued source, HTTP 200 test response with success=false, and SSE error event are unsuccessful operations despite their HTTP response being successful.