Notebooks¶

Notebooks are the top-level organizational unit. Each notebook has its own documents, conversations, settings, and vector store. Notebooks are scoped to a database type (cloud or local) and a storage provider.

Base path: /api/notebooks

POST /api/notebooks/¶

Create a new notebook with default settings. The notebook_id is client-generated (typically crypto.randomUUID()). The embedding_model is locked at creation time and cannot be changed later.

Auth: Admin

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Body:

{
  "notebook_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notebook_title": "Customer Support KB",
  "notebook_description": "Knowledge base for support agents",
  "icon": "\ud83d\udcca",
  "embedding_model": "openai/text-embedding-3-small",
  "db_type": "cloud",
  "storage_provider": "supabase",
  "user_id": "user_abc123"
}

Field	Type	Required	Default	Description
`notebook_id`	string	Yes	--	Client-generated UUID
`notebook_title`	string	Yes	--	Notebook title (1-200 chars)
`notebook_description`	string	No	`""`	Optional description
`icon`	string	No	`"\ud83d\udcca"`	Emoji icon
`embedding_model`	string	No	`"openai/text-embedding-3-small"`	Embedding model (immutable after creation)
`db_type`	string	No	`"cloud"`	`"cloud"` or `"local"`
`storage_provider`	string	No	`"supabase"`	`"supabase"`, `"s3"`, `"local"`, or `"none"`
`user_id`	string	Yes	--	Owner user ID (auto-filled from auth if empty)

Status: 201 Created

{
  "success": true,
  "data": {
    "notebook_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "notebook_title": "Customer Support KB",
    "notebook_description": "Knowledge base for support agents",
    "icon": "\ud83d\udcca",
    "db_type": "cloud",
    "storage_provider": "supabase",
    "number_of_documents": 0,
    "created_at": "2026-02-25T10:00:00Z",
    "updated_at": "2026-02-25T10:00:00Z"
  }
}

Code	Cause
`400`	Invalid `db_type` or `storage_provider` value
`400`	Missing or empty `notebook_title`
`401`	Invalid or missing token
`403`	Non-admin user

curl -X POST http://localhost:8000/api/notebooks/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notebook_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "notebook_title": "Customer Support KB",
    "user_id": "dev-user"
  }'

import httpx
import uuid

response = httpx.post(
    "http://localhost:8000/api/notebooks/",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "notebook_id": str(uuid.uuid4()),
        "notebook_title": "Customer Support KB",
        "user_id": "dev-user",
    },
)
notebook = response.json()["data"]
print(f"Created: {notebook['notebook_id']}")

GET /api/notebooks/¶

List all notebooks with file-job status counts. Queries both cloud and local databases if configured. Admins see all notebooks; non-admins see only notebooks shared with them.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`

Status: 200 OK

{
  "success": true,
  "data": [
    {
      "notebook_id": "a1b2c3d4-...",
      "notebook_title": "Customer Support KB",
      "notebook_description": "",
      "icon": "\ud83d\udcca",
      "db_type": "cloud",
      "storage_provider": "supabase",
      "number_of_documents": 12,
      "pending_count": 0,
      "processing_count": 0,
      "error_count": 1,
      "success_count": 11,
      "total_files": 12,
      "is_finished": true,
      "created_at": "2026-02-25T10:00:00Z",
      "updated_at": "2026-02-25T12:00:00Z"
    }
  ]
}

Code	Cause
`401`	Invalid or missing token

curl http://localhost:8000/api/notebooks/ \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.get(
    "http://localhost:8000/api/notebooks/",
    headers={"Authorization": f"Bearer {token}"},
)
notebooks = response.json()["data"]
for nb in notebooks:
    print(f"{nb['notebook_title']} ({nb['total_files']} files)")

GET /api/notebooks/{notebook_id}¶

Get a single notebook by ID. Auto-resolves the correct database (cloud or local).

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`

Status: 200 OK

{
  "success": true,
  "data": {
    "notebook_id": "a1b2c3d4-...",
    "notebook_title": "Customer Support KB",
    "notebook_description": "",
    "icon": "\ud83d\udcca",
    "db_type": "cloud",
    "storage_provider": "supabase",
    "number_of_documents": 12,
    "created_at": "2026-02-25T10:00:00Z",
    "updated_at": "2026-02-25T12:00:00Z"
  }
}

Code	Cause
`401`	Invalid or missing token
`404`	Notebook not found

curl http://localhost:8000/api/notebooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TOKEN"

import httpx

notebook_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = httpx.get(
    f"http://localhost:8000/api/notebooks/{notebook_id}",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.json()["data"])

GET /api/notebooks/{notebook_id}/status¶

Get detailed notebook status including document stats, conversation stats, enhancement stats, and file job details.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`

Status: 200 OK

{
  "success": true,
  "data": {
    "notebook": {
      "notebook_id": "a1b2c3d4-...",
      "notebook_title": "Customer Support KB",
      "number_of_documents": 12
    },
    "documents": {
      "total_documents": 12,
      "total_chunks": 340,
      "tabular_documents": 2,
      "non_tabular_documents": 10
    },
    "conversations": {
      "total_conversations": 5,
      "total_messages": 48
    },
    "enhancement": {
      "total_chunks": 340,
      "enhanced_chunks": 200,
      "pending_chunks": 100,
      "failed_chunks": 3
    },
    "file_jobs": [
      {
        "file_id": "...",
        "file_name": "handbook.pdf",
        "status": "success"
      }
    ]
  }
}

Code	Cause
`401`	Invalid or missing token
`404`	Notebook not found

curl http://localhost:8000/api/notebooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status \
  -H "Authorization: Bearer $TOKEN"

import httpx

notebook_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = httpx.get(
    f"http://localhost:8000/api/notebooks/{notebook_id}/status",
    headers={"Authorization": f"Bearer {token}"},
)
status = response.json()["data"]
print(f"Chunks: {status['documents']['total_chunks']}")
print(f"Enhanced: {status['enhancement']['enhanced_chunks']}")

PATCH /api/notebooks/{notebook_id}¶

Update a notebook's title and/or description.

Auth: Admin

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Body:

{
  "notebook_title": "Updated Title",
  "notebook_description": "New description"
}

Field	Type	Required	Default	Description
`notebook_title`	string	No	--	New title
`notebook_description`	string	No	--	New description

Status: 200 OK

{
  "success": true,
  "data": {
    "notebook_id": "a1b2c3d4-...",
    "notebook_title": "Updated Title",
    "notebook_description": "New description",
    "updated_at": "2026-02-25T14:00:00Z"
  }
}

Code	Cause
`401`	Invalid or missing token
`403`	Non-admin user
`404`	Notebook not found

curl -X PATCH http://localhost:8000/api/notebooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notebook_title": "Updated Title"}'

import httpx

notebook_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = httpx.patch(
    f"http://localhost:8000/api/notebooks/{notebook_id}",
    headers={"Authorization": f"Bearer {token}"},
    json={"notebook_title": "Updated Title"},
)
print(response.json()["data"])

DELETE /api/notebooks/all¶

Delete all notebooks and their related data. This is a destructive operation.

Auth: Admin

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`

Status: 200 OK

{
  "success": true,
  "data": {
    "deleted": 5
  }
}

Code	Cause
`401`	Invalid or missing token
`403`	Non-admin user

curl -X DELETE http://localhost:8000/api/notebooks/all \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.delete(
    "http://localhost:8000/api/notebooks/all",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.json()["data"])

Destructive Operation

This permanently deletes all notebooks, documents, conversations, and vector data. There is no undo.

DELETE /api/notebooks/{notebook_id}¶

Delete a single notebook and all related data via database cascade (RPC call).

Auth: Admin

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`

Status: 200 OK

{
  "success": true,
  "data": {
    "notebook_id": "a1b2c3d4-...",
    "notebook_title": "Customer Support KB",
    "documents_deleted": 12,
    "document_records_deleted": 12,
    "jobs_deleted": 12,
    "chunks_deleted": 340,
    "chat_messages_deleted": 48,
    "conversations_deleted": 5,
    "raw_data_deleted": 12,
    "cache_deleted": 8,
    "deleted_at": "2026-02-25T15:00:00Z"
  }
}

Code	Cause
`401`	Invalid or missing token
`403`	Non-admin user
`404`	Notebook not found

curl -X DELETE http://localhost:8000/api/notebooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TOKEN"

import httpx

notebook_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = httpx.delete(
    f"http://localhost:8000/api/notebooks/{notebook_id}",
    headers={"Authorization": f"Bearer {token}"},
)
result = response.json()["data"]
print(f"Deleted {result['chunks_deleted']} chunks")