Notes - Open WebUI

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:

# 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"
    }
  ]
}

Set Title

Choose a descriptive title for easy identification

Write Content

Use markdown formatting in the data.content.md field

Add Metadata

Include tags, categories, or custom fields in meta

Configure Access

Define who can read or edit the note (optional)

Viewing Notes

List Your Notes

Retrieve notes you can access:

# 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:

Text Search
View Options
Permission Filter
Sorting

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:

# 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

# Notes you can edit
GET /api/v1/notes/search?permission=write

# Notes you can read
GET /api/v1/notes/search?permission=read

# 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:

# API endpoint: GET /api/v1/notes/{id}

Response includes:

{
  "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:

# 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:

# 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:

// 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

Read Access
Write Access
Owner

Users can:

View note content
See note metadata
Include in search results
Clone/export the note

Configuring Access

Set up access grants for notes:

# 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

User Access

Grant access to specific users by ID

Group Access

All group members inherit access automatically

Public Access

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:

Create Groups

Set up user groups (e.g., “Marketing Team”, “Engineering”)

Grant Group Access

Add group to note’s access grants

Automatic Propagation

All group members immediately see the note in their list

Dynamic Updates

Adding users to the group automatically grants note access

Content Formatting

Markdown Support

Notes use markdown for rich text formatting:

Basic Formatting
Links & Images
Code Blocks
Tables

# Heading 1
## Heading 2
### Heading 3

**Bold text**
*Italic text*
~~Strikethrough~~

- Bullet list
- Another item

1. Numbered list
2. Second item

[Link text](https://example.com)

![Image alt text](https://example.com/image.png)

Inline `code` with backticks

```python
# Code block with syntax highlighting
def hello():
    print("Hello, World!")
```

| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |
| Data 3   | Data 4   |

Content Storage

Note content is stored in a structured format:

{
  "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:

# 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

Title Search

Note titles are indexed for fast lookups

Content Search

Full markdown content is searchable

Access Filter

Results automatically filtered by permissions

Group Integration

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

# 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:

# 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

{
  "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

Tags
Custom Metadata

Simple string arrays
Good for categories and topics
Easy to filter and group
Commonly used in UI

Best Practices

Note Organization

Use Descriptive Titles

Choose clear, searchable titles:

✅ “Q1 2024 Marketing Strategy”
✅ “API Integration Guide - Stripe”
❌ “Notes”, “Untitled”, “Test”

Apply Consistent Tags

Develop a tagging taxonomy:

Project names
Document types
Departments
Status indicators

Set Appropriate Access

Start restrictive, expand as needed:

Personal notes: Owner only
Team notes: Group access
Public docs: Organization-wide read

Regular Maintenance

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:

# 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

Use Filters

Narrow results at the database level instead of client-side

Pagination

Load notes incrementally for better performance

Limit Fields

Use list endpoints for previews, detail endpoint for full content

Cache Results

Leverage HTTP caching headers

Admin Features

Access Control Override

Admins can optionally bypass restrictions:

# 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

List Notes

GET /api/v1/notes/?page=1

Paginated note list (60 per page)

Search Notes

GET /api/v1/notes/search?query=...

Advanced filtering and sorting

Get Note

GET /api/v1/notes/{id}

Full note content and metadata

Create Note

POST /api/v1/notes/create

Create new note with content

Update Note

POST /api/v1/notes/{id}/update

Modify content or metadata

Update Access

POST /api/v1/notes/{id}/access/update

Manage access grants

Delete Note

DELETE /api/v1/notes/{id}/delete

Permanently remove note

All endpoints require authentication and respect note access controls.

​Overview

​Creating Notes

​Viewing Notes

​List Your Notes

​Search Notes

​Get Note Details

​Editing Notes

​Partial Updates

​Real-Time Sync

​Access Control

​Permission Levels

​Configuring Access

​Access Grant Types

User Access

Group Access

Public Access

​Group-Based Access

​Content Formatting

​Markdown Support

​Content Storage

​Search & Discovery

​Text Normalization

​Search Scope

Title Search

Content Search

Access Filter

Group Integration

​Pagination

​Deleting Notes

​Metadata Management

​Common Metadata Fields

​Tags vs. Metadata

​Best Practices

​Note Organization

​Content Guidelines

​Collaboration

​Performance Optimization

​Content Truncation

​Efficient Querying

Use Filters

Pagination

Limit Fields

Cache Results

​Admin Features

​Access Control Override

​API Reference

List Notes

Search Notes

Get Note

Create Note

Update Note

Update Access

Delete Note

Overview

Creating Notes

Viewing Notes

List Your Notes

Search Notes

Get Note Details

Editing Notes

Partial Updates

Real-Time Sync

Access Control

Permission Levels

Configuring Access

Access Grant Types

Group-Based Access

Content Formatting

Markdown Support

Content Storage

Search & Discovery

Text Normalization

Search Scope

Pagination

Deleting Notes

Metadata Management

Common Metadata Fields

Tags vs. Metadata

Best Practices

Note Organization

Content Guidelines

Collaboration

Performance Optimization

Content Truncation

Efficient Querying

Admin Features

Access Control Override

API Reference