builderadmin
/
NoteDiscovery
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity
NoteDiscovery/documentation/API.md

14 KiB
Raw Blame History

📡 API Documentation

Base URL: http://localhost:8000

🗂️ Notes

List All Notes

GET /api/notes
GET /api/notes?limit=20&offset=0

Returns all notes with their metadata and folder structure.

Optional Pagination:

Parameter Type Default Description
limit integer - Max notes to return (omit for all)
offset integer 0 Number of notes to skip

When limit is provided, the response includes pagination metadata.

Examples:

# Get all notes (default)
curl http://localhost:8000/api/notes

# Get first 20 notes
curl "http://localhost:8000/api/notes?limit=20"

# Get notes 21-40
curl "http://localhost:8000/api/notes?limit=20&offset=20"

Get Note Content

GET /api/notes/{note_path}

Retrieve the content of a specific note, including metadata and backlinks.

Query Parameters:

Parameter Type Default Description
include_backlinks boolean true Include backlinks (notes that link to this note)

Example:

curl http://localhost:8000/api/notes/folder/mynote.md

Response:

{
  "path": "folder/mynote.md",
  "content": "# My Note\n\nNote content here...",
  "metadata": {
    "created": "2026-03-15T10:00:00+01:00",
    "modified": "2026-03-17T14:30:00+01:00",
    "size": 1234,
    "lines": 42
  },
  "backlinks": [
    {
      "path": "meetings/standup.md",
      "name": "standup",
      "references": [
        {
          "line_number": 15,
          "context": "...discussed [[mynote]]...",
          "type": "wikilink"
        }
      ]
    }
  ]
}

Backlinks Response Fields:

Field Description
path Path of the note that links to this note
name Display name of the linking note
references Array of link occurrences (max 3 per note)
references[].line_number Line number where the link appears
references[].context Text snippet around the link
references[].type Link type: wikilink or markdown

Without Backlinks:

curl "http://localhost:8000/api/notes/folder/mynote.md?include_backlinks=false"

Create/Update Note

POST /api/notes/{note_path}
Content-Type: application/json

{
  "content": "# My Note\nNote content here..."
}

Response:

{
  "success": true,
  "path": "test.md",
  "message": "Note created successfully",
  "content": "# My Note\nNote content here..."
}

Note: When creating a new note, the on_note_create hook is triggered, allowing plugins to modify the initial content. The response includes the potentially modified content.

Linux/Mac:

curl -X POST http://localhost:8000/api/notes/test.md \
  -H "Content-Type: application/json" \
  -d '{"content": "# Hello World"}'

Windows PowerShell:

curl.exe -X POST http://localhost:8000/api/notes/test.md -H "Content-Type: application/json" -d "{\"content\": \"# Hello World\"}"

Delete Note

DELETE /api/notes/{note_path}

Example:

curl -X DELETE http://localhost:8000/api/notes/test.md

Append to Note

PATCH /api/notes/{note_path}
Content-Type: application/json

{
  "content": "Content to append...",
  "add_timestamp": true
}

Append content to an existing note without overwriting. Perfect for journals, logs, or collecting ideas incrementally.

Parameters:

Parameter Type Required Description
content string Yes Content to append to the note
add_timestamp boolean No If true, prepends a timestamp header (default: false)

Response:

{
  "success": true,
  "path": "daily-journal.md",
  "message": "Content appended successfully"
}

Example with timestamp:

curl -X PATCH http://localhost:8000/api/notes/daily-journal.md \
  -H "Content-Type: application/json" \
  -d '{"content": "Had a productive meeting about the roadmap.", "add_timestamp": true}'

This will append:


---

**2024-03-13 14:30**

Had a productive meeting about the roadmap.

Windows PowerShell:

curl.exe -X PATCH http://localhost:8000/api/notes/daily-journal.md -H "Content-Type: application/json" -d "{\"content\": \"New entry here\", \"add_timestamp\": true}"

Move Note

POST /api/notes/move
Content-Type: application/json

{
  "oldPath": "note.md",
  "newPath": "folder/note.md"
}

🎬 Media

Get Media

GET /api/media/{media_path}

Retrieve a media file (image, audio, video, PDF) with authentication protection.

Example:

curl http://localhost:8000/api/media/folder/_attachments/image-20240417093343.png

Security Note: This endpoint requires authentication and validates that:

  • The media path is within the notes directory (prevents directory traversal)
  • The file exists and is a valid media format
  • The requesting user is authenticated (if auth is enabled)

Upload Media

POST /api/upload-media
Content-Type: multipart/form-data

file: <media file>
note_path: <path of note to attach to>

Upload a media file to the _attachments directory. Files are automatically organized per-folder and named with timestamps to prevent conflicts.

Supported formats & size limits:

Type Formats Max Size
Images JPG, PNG, GIF, WebP 10 MB
Audio MP3, WAV, OGG, M4A 50 MB
Video MP4, WebM, MOV, AVI 100 MB
Documents PDF 20 MB

Response:

{
  "success": true,
  "path": "folder/_attachments/media-20240417093343.png",
  "filename": "media-20240417093343.png",
  "message": "Media uploaded successfully"
}

Example (using curl):

curl -X POST http://localhost:8000/api/upload-media \
  -F "file=@/path/to/file.mp3" \
  -F "note_path=folder/mynote.md"

Windows PowerShell:

curl.exe -X POST http://localhost:8000/api/upload-media -F "file=@C:\path\to\video.mp4" -F "note_path=folder/mynote.md"

Move Media

POST /api/media/move
Content-Type: application/json

{
  "oldPath": "_attachments/image.png",
  "newPath": "folder/_attachments/image.png"
}

Move a media file to a different location. Supports drag & drop in the UI.

Response:

{
  "success": true,
  "message": "Media moved successfully",
  "newPath": "folder/_attachments/image.png"
}

Notes:

  • Media is stored in _attachments folders relative to the note's location
  • Filenames are automatically timestamped (e.g., media-20240417093343.mp3)
  • Media appears in the sidebar navigation and can be viewed/deleted directly
  • Drag & drop files into the editor automatically uploads and inserts markdown
  • All media access requires authentication when security is enabled

📁 Folders

Create Folder

POST /api/folders
Content-Type: application/json

{
  "path": "Projects/2025"
}

Delete Folder

DELETE /api/folders/{folder_path}

Deletes a folder and all its contents.

Example:

curl -X DELETE http://localhost:8000/api/folders/Projects/Archive

Move Folder

POST /api/folders/move
Content-Type: application/json

{
  "oldPath": "OldFolder",
  "newPath": "NewFolder"
}

Rename Folder

POST /api/folders/rename
Content-Type: application/json

{
  "oldPath": "Projects",
  "newName": "Work"
}

🔍 Search

Search Notes

GET /api/search?q={query}
GET /api/search?q={query}&limit=10&offset=0

Optional Pagination:

Parameter Type Default Description
limit integer - Max results to return (omit for all)
offset integer 0 Number of results to skip

Examples:

# Search all matches
curl "http://localhost:8000/api/search?q=hello"

# Get first 10 results
curl "http://localhost:8000/api/search?q=hello&limit=10"

🎨 Themes

List Themes

GET /api/themes

Get Theme CSS

GET /api/themes/{theme_id}

Example:

curl http://localhost:8000/api/themes/dark

🔌 Plugins

Plugins can hook into various events in the application lifecycle.

Available Plugin Hooks

Hook Triggered When Can Modify Data
on_note_create New note is created ✅ Yes (return modified content)
on_note_save Note is being saved ✅ Yes (return transformed content, or None)
on_note_load Note is loaded ✅ Yes (return transformed content, or None)
on_note_delete Note is deleted ❌ No
on_search Search is performed ❌ No
on_app_startup App starts ❌ No

See PLUGINS.md for full documentation on creating plugins.

List Plugins

GET /api/plugins

Toggle Plugin

POST /api/plugins/{plugin_name}/toggle
Content-Type: application/json

{
  "enabled": true
}

Linux/Mac:

curl -X POST http://localhost:8000/api/plugins/note_stats/toggle \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Windows PowerShell:

curl.exe -X POST http://localhost:8000/api/plugins/note_stats/toggle -H "Content-Type: application/json" -d "{\"enabled\": true}"

Calculate Note Stats

GET /api/plugins/note_stats/calculate?content={markdown_content}

🔗 Graph

Get Note Graph

GET /api/graph

Returns the relationship graph between notes with link detection.

Response:

{
  "nodes": [
    { "id": "folder/note.md", "label": "note" },
    { "id": "another.md", "label": "another" }
  ],
  "edges": [
    { "source": "folder/note.md", "target": "another.md", "type": "wikilink" }
  ]
}

Link Detection:

  • Wikilinks - [[note]] or [[note|display text]] syntax (Obsidian-style)
  • Markdown links - [text](note.md) standard internal links
  • Edge types - "wikilink" or "markdown" to distinguish link source

⚙️ System

Get Config

GET /api/config

Returns application configuration.

Health Check

GET /health

Returns system health status.

Swagger UI (Interactive Docs)

GET /api

Interactive API documentation with try-it-out functionality (Swagger UI).

🏷️ Tags

List All Tags

GET /api/tags

Returns all tags found in notes with their usage counts.

Response:

{
  "tags": {
    "python": 5,
    "tutorial": 3,
    "backend": 2
  }
}

Get Notes by Tag

GET /api/tags/{tag_name}
GET /api/tags/{tag_name}?limit=10&offset=0

Returns all notes that have a specific tag.

Optional Pagination:

Parameter Type Default Description
limit integer - Max notes to return (omit for all)
offset integer 0 Number of notes to skip

Response:

{
  "tag": "python",
  "count": 5,
  "notes": [
    {
      "path": "tutorials/python-basics.md",
      "name": "python-basics",
      "folder": "tutorials",
      "tags": ["python", "tutorial"]
    }
  ]
}

📄 Templates

List Templates

GET /api/templates

Returns all available note templates from the _templates folder.

Response:

{
  "templates": [
    {
      "name": "meeting-notes",
      "path": "_templates/meeting-notes.md",
      "modified": "2025-11-26T10:30:00"
    },
    {
      "name": "daily-journal",
      "path": "_templates/daily-journal.md",
      "modified": "2025-11-26T10:25:00"
    }
  ]
}

Get Template Content

GET /api/templates/{template_name}

Returns the content of a specific template.

Parameters:

  • template_name - Template name (without .md extension)

Response:

{
  "name": "meeting-notes",
  "content": "# Meeting Notes\n\nDate: {{date}}\n..."
}

Create Note from Template

POST /api/templates/create-note

Creates a new note from a template with placeholder replacement.

Request Body:

{
  "templateName": "meeting-notes",
  "notePath": "meetings/weekly-sync.md"
}

Placeholders:

  • {{date}} - Current date (YYYY-MM-DD)
  • {{time}} - Current time (HH:MM:SS)
  • {{datetime}} - Current datetime
  • {{timestamp}} - Unix timestamp
  • {{year}} - Current year (YYYY)
  • {{month}} - Current month (MM)
  • {{day}} - Current day (DD)
  • {{title}} - Note name without extension
  • {{folder}} - Parent folder name

Response:

{
  "success": true,
  "path": "meetings/weekly-sync.md",
  "message": "Note created from template successfully",
  "content": "# Meeting Notes\n\nDate: 2025-11-26\n..."
}

🔗 Sharing

Share notes publicly without requiring authentication.

Create Share Link

POST /api/share/{note_path}
Content-Type: application/json

{
  "theme": "dracula"
}

Creates a share token for the note. The theme is optional (defaults to "light").

Response:

{
  "success": true,
  "token": "LRFEo86oSVeJ3Gju",
  "url": "http://localhost:8000/share/LRFEo86oSVeJ3Gju",
  "note_path": "folder/note.md"
}

Get Share Status

GET /api/share/{note_path}

Check if a note is currently shared.

Response:

{
  "shared": true,
  "token": "LRFEo86oSVeJ3Gju",
  "url": "http://localhost:8000/share/LRFEo86oSVeJ3Gju",
  "theme": "dracula",
  "created": "2026-01-15T10:30:00+00:00"
}

Revoke Share

DELETE /api/share/{note_path}

Removes public access to the note.

List Shared Notes

GET /api/shared-notes

Returns paths of all currently shared notes.

Response:

{
  "paths": ["folder/note.md", "another.md"]
}

View Shared Note (Public)

GET /share/{token}

Public endpoint - no authentication required. Returns the note as a standalone HTML page with the theme set when sharing was created.

📝 Response Format

All endpoints return JSON responses:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "detail": "Error message"
}

💡 Tip: Visit /api for interactive Swagger UI documentation where you can try endpoints directly in your browser!