> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.
# Notes
> Create, organize, and share personal and collaborative notes with rich text formatting
## Overview
Open WebUI's Notes feature provides a collaborative note-taking system with markdown support, access control, and real-time synchronization. Perfect for documentation, knowledge management, and team collaboration.
Notes functionality requires the `features.notes` permission for non-admin users.
## Creating Notes
Create personal or shared notes:
```python theme={null}
# API endpoint: POST /api/v1/notes/create
{
"title": "Meeting Notes - Q1 Planning",
"data": {
"content": {
"md": "# Q1 Planning\n\n## Goals\n- Launch new feature\n- Improve performance"
}
},
"meta": {
"tags": ["meeting", "planning", "q1"]
},
"access_grants": [
{
"principal_type": "user",
"principal_id": "user-123",
"permission": "write"
}
]
}
```
Choose a descriptive title for easy identification
Use markdown formatting in the `data.content.md` field
Include tags, categories, or custom fields in `meta`
Define who can read or edit the note (optional)
## Viewing Notes
### List Your Notes
Retrieve notes you can access:
```bash theme={null}
# API endpoint: GET /api/v1/notes/?page=1
# Returns 60 notes per page, sorted by last updated
```
Response includes:
* **Note ID**: Unique identifier
* **Title**: Note name
* **Truncated Content**: First 1000 characters of markdown
* **User Info**: Note owner details
* **Timestamps**: Created and updated times
### Search Notes
Find notes with advanced filtering:
```bash theme={null}
GET /api/v1/notes/search?query=planning&page=1
```
Searches in:
* Note titles
* Markdown content
* Normalized text (spaces and hyphens treated equally)
Filter by ownership:
```bash theme={null}
# Created by you
GET /api/v1/notes/search?view_option=created
# Shared with you
GET /api/v1/notes/search?view_option=shared
# All accessible notes
GET /api/v1/notes/search?view_option=all
```
```bash theme={null}
# Notes you can edit
GET /api/v1/notes/search?permission=write
# Notes you can read
GET /api/v1/notes/search?permission=read
```
```bash theme={null}
# Sort by name
GET /api/v1/notes/search?order_by=name&direction=asc
# Sort by creation date
GET /api/v1/notes/search?order_by=created_at&direction=desc
# Sort by last update (default)
GET /api/v1/notes/search?order_by=updated_at&direction=desc
```
### Get Note Details
Retrieve full note content:
```bash theme={null}
# API endpoint: GET /api/v1/notes/{id}
```
Response includes:
```json theme={null}
{
"id": "note-123",
"user_id": "owner-id",
"title": "My Note",
"data": {
"content": {
"md": "Full markdown content..."
}
},
"meta": {...},
"access_grants": [...],
"write_access": true,
"created_at": 1234567890,
"updated_at": 1234567900
}
```
The `write_access` field indicates whether you can edit the note.
## Editing Notes
Update note content or metadata:
```python theme={null}
# API endpoint: POST /api/v1/notes/{id}/update
{
"title": "Updated Title",
"data": {
"content": {
"md": "# Updated Content\n\nNew information here..."
}
},
"meta": {
"tags": ["updated", "new-tag"]
}
}
```
### Partial Updates
Update specific fields without affecting others:
```python theme={null}
# Update only the title
{"title": "New Title"}
# Update only metadata
{"meta": {"priority": "high"}}
# Update only content
{"data": {"content": {"md": "New content"}}}
```
Data and metadata are merged with existing values, not replaced entirely.
### Real-Time Sync
Notes emit WebSocket events on update:
```javascript theme={null}
// Clients subscribed to room: note:{note_id}
// Receive event: note-events
{
"id": "note-123",
"title": "Updated Note",
"data": {...},
"updated_at": 1234567900
}
```
Use for:
* **Collaborative Editing**: Multiple users see changes instantly
* **Auto-Save Indicators**: Show when note was last saved
* **Conflict Resolution**: Detect concurrent edits
## Access Control
### Permission Levels
Users can:
* View note content
* See note metadata
* Include in search results
* Clone/export the note
Users can (in addition to read):
* Edit note content
* Update metadata
* Manage access grants
* Delete the note
Note creator has:
* Full write access
* Cannot be revoked
* Permanent ownership (no transfer)
### Configuring Access
Set up access grants for notes:
```python theme={null}
# API endpoint: POST /api/v1/notes/{id}/access/update
{
"access_grants": [
{
"principal_type": "user",
"principal_id": "user-123",
"permission": "write"
},
{
"principal_type": "group",
"principal_id": "group-engineering",
"permission": "read"
},
{
"principal_type": "user",
"principal_id": "*", # Public access
"permission": "read"
}
]
}
```
### Access Grant Types
Grant access to specific users by ID
All group members inherit access automatically
Use `principal_id: "*"` for organization-wide sharing
Public note sharing requires the `sharing.public_notes` permission for non-admin users.
### Group-Based Access
Notes automatically become available to users based on group membership:
Set up user groups (e.g., "Marketing Team", "Engineering")
Add group to note's access grants
All group members immediately see the note in their list
Adding users to the group automatically grants note access
## Content Formatting
### Markdown Support
Notes use markdown for rich text formatting:
```markdown theme={null}
# Heading 1
## Heading 2
### Heading 3
**Bold text**
*Italic text*
~~Strikethrough~~
- Bullet list
- Another item
1. Numbered list
2. Second item
```
```markdown theme={null}
[Link text](https://example.com)
```
````markdown theme={null}
Inline `code` with backticks
```python
# Code block with syntax highlighting
def hello():
print("Hello, World!")
```
````
```markdown theme={null}
| Column 1 | Column 2 |
|----------|----------|
| Data 1 | Data 2 |
| Data 3 | Data 4 |
```
### Content Storage
Note content is stored in a structured format:
```json theme={null}
{
"data": {
"content": {
"md": "# Your markdown here"
},
"custom_field": "Additional data..."
}
}
```
The `data` object supports custom fields for application-specific metadata.
## Search & Discovery
### Text Normalization
Search intelligently handles variations:
```bash theme={null}
# These queries all match "to-do", "to do", and "todo"
GET /api/v1/notes/search?query=todo
GET /api/v1/notes/search?query=to-do
GET /api/v1/notes/search?query=to%20do
```
Normalization:
* **Spaces and hyphens** treated as equivalent
* **Case insensitive** matching
* **Partial matches** in title and content
### Search Scope
Note titles are indexed for fast lookups
Full markdown content is searchable
Results automatically filtered by permissions
Group membership affects visible results
### Pagination
Efficient handling of large note collections:
* **Default**: 60 notes per page
* **Customizable**: Use `limit` parameter in API
* **Total Count**: Response includes total matching notes
* **Offset-Based**: Use `skip` for custom pagination
```bash theme={null}
# Get notes 61-120
GET /api/v1/notes/search?page=2
# Custom pagination
GET /api/v1/notes/?skip=100&limit=25
```
## Deleting Notes
Remove notes permanently:
```bash theme={null}
# API endpoint: DELETE /api/v1/notes/{id}/delete
```
Permission requirements:
* **Owner**: Can always delete
* **Write Access**: Can delete if granted
* **Admin**: Can delete any note
Deleting a note:
* Removes all content permanently
* Revokes all access grants
* Cannot be undone
* No trash/recovery mechanism
## Metadata Management
Organize notes with custom metadata:
### Common Metadata Fields
```json theme={null}
{
"meta": {
"tags": ["project-x", "meeting", "important"],
"category": "documentation",
"priority": "high",
"due_date": "2024-12-31",
"assignee": "user-123",
"status": "in-progress"
}
}
```
Use consistent metadata schemas across your organization for better organization and filtering.
### Tags vs. Metadata
* Simple string arrays
* Good for categories and topics
* Easy to filter and group
* Commonly used in UI
* Structured data
* Application-specific fields
* Rich data types
* Extensible schema
## Best Practices
### Note Organization
Choose clear, searchable titles:
* ✅ "Q1 2024 Marketing Strategy"
* ✅ "API Integration Guide - Stripe"
* ❌ "Notes", "Untitled", "Test"
Develop a tagging taxonomy:
* Project names
* Document types
* Departments
* Status indicators
Start restrictive, expand as needed:
* Personal notes: Owner only
* Team notes: Group access
* Public docs: Organization-wide read
Keep notes relevant:
* Archive outdated content
* Update access as teams change
* Remove duplicate notes
### Content Guidelines
* **Structure Content**: Use headers for scannable notes
* **Link References**: Connect related notes and resources
* **Version Important Changes**: Note major updates in content
* **Keep It Concise**: Break long documents into multiple notes
### Collaboration
* **Write Access**: Grant to active collaborators only
* **Read Access**: Share broadly for visibility
* **Use Groups**: Easier than individual user grants
* **Real-Time Awareness**: Leverage WebSocket events for collaboration
## Performance Optimization
### Content Truncation
List views automatically truncate content:
```python theme={null}
# In list/search results
"data": {
"content": {
"md": "First 1000 characters only..."
}
}
```
Benefits:
* **Faster Loading**: Reduced payload size
* **Better UX**: Quick previews
* **Scalability**: Handles large note collections
### Efficient Querying
Narrow results at the database level instead of client-side
Load notes incrementally for better performance
Use list endpoints for previews, detail endpoint for full content
Leverage HTTP caching headers
## Admin Features
### Access Control Override
Admins can optionally bypass restrictions:
```python theme={null}
# Configuration option
BYPASS_ADMIN_ACCESS_CONTROL = True
```
When enabled, admins:
* View all notes regardless of access grants
* Modify any note content
* Manage access for all users
* Delete any note
Use admin override carefully. It bypasses all permission checks.
## API Reference
```
GET /api/v1/notes/?page=1
```
Paginated note list (60 per page)
```
GET /api/v1/notes/search?query=...
```
Advanced filtering and sorting
```
GET /api/v1/notes/{id}
```
Full note content and metadata
```
POST /api/v1/notes/create
```
Create new note with content
```
POST /api/v1/notes/{id}/update
```
Modify content or metadata
```
POST /api/v1/notes/{id}/access/update
```
Manage access grants
```
DELETE /api/v1/notes/{id}/delete
```
Permanently remove note
All endpoints require authentication and respect note access controls.